diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog index a4603d22a..9198e545f 100644 --- a/winsup/doc/ChangeLog +++ b/winsup/doc/ChangeLog @@ -1,3 +1,23 @@ +2014-08-14 Corinna Vinschen + + * Makefile.in: Throughout use parenthesis instead of braces where + appropriate. + (DBXDIRS): Remove. + (XSLTPROC): Define for symmetry. Use throughout. + (clean): Drop removing cygwin-api.xml and doctool.*. + (cygwin-api.xml): Drop rule. + (doctool): Drop rule. + (Makefile.dep): Add dependency to cygwin-api.xml. + * cygwin-api.in.xml: Rename to cygwin-api.xml. Convert includes to + XML XInclude style. + * doctool.c: Remove. + * doctool.txt: Remove. + * faq-programming.xml: Drop reference to local utils.xml file. + * path.xml: Moved from ../cygwin and converted to XML. + * posix.xml: Ditto. + * using.xml: Drop relative path from utils.xml include. + * utils.xml: Moved from ../utils. + 2014-08-13 Corinna Vinschen * new-features.xml: (ov-new1.7.33): Add new section. diff --git a/winsup/doc/Makefile.in b/winsup/doc/Makefile.in index 8bc583149..ae4694271 100644 --- a/winsup/doc/Makefile.in +++ b/winsup/doc/Makefile.in @@ -12,16 +12,15 @@ SHELL = @SHELL@ srcdir = @srcdir@ VPATH = @srcdir@ -DBXDIRS = -d $(srcdir) -d $(srcdir)/../utils -d $(srcdir)/../cygwin - CC:=@CC@ CC_FOR_TARGET:=@CC@ +XSLTPROC:=xsltproc --xinclude XMLTO:=xmlto --skip-validation --with-dblatex include $(srcdir)/../Makefile.common -FAQ_SOURCES:= $(wildcard ${srcdir}/faq*.xml) +FAQ_SOURCES:= $(wildcard $(srcdir)/faq*.xml) .SUFFIXES: .html .body @@ -36,46 +35,38 @@ all: Makefile Makefile.dep \ cygwin-ug-net/cygwin-ug-net.pdf \ cygwin-api/cygwin-api.pdf -Makefile: ${srcdir}/Makefile.in +Makefile: $(srcdir)/Makefile.in /bin/sh ./config.status clean: rm -f Makefile.dep - rm -f doctool.exe doctool.o - rm -f cygwin-api.xml rm -f *.html *.html.gz rm -Rf cygwin-api cygwin-ug cygwin-ug-net faq install: all cygwin-ug-net/cygwin-ug-net-nochunks.html.gz : cygwin-ug-net.xml - -${XMLTO} html-nochunks -m $(srcdir)/cygwin.xsl $< + -$(XMLTO) html-nochunks -m $(srcdir)/cygwin.xsl $< -cp cygwin-ug-net.html cygwin-ug-net/cygwin-ug-net-nochunks.html -rm -f cygwin-ug-net/cygwin-ug-net-nochunks.html.gz -gzip cygwin-ug-net/cygwin-ug-net-nochunks.html cygwin-ug-net/cygwin-ug-net.html : cygwin-ug-net.xml cygwin.xsl - -${XMLTO} html -o cygwin-ug-net/ -m $(srcdir)/cygwin.xsl $< + -$(XMLTO) html -o cygwin-ug-net/ -m $(srcdir)/cygwin.xsl $< cygwin-ug-net/cygwin-ug-net.pdf : cygwin-ug-net.xml fo.xsl - -xsltproc --xinclude $(srcdir)/fo.xsl $< | fop -q -fo - $@ + -$(XSLTPROC) $(srcdir)/fo.xsl $< | fop -q -fo - $@ cygwin-api/cygwin-api.html : cygwin-api.xml cygwin.xsl - -${XMLTO} html -o cygwin-api/ -m $(srcdir)/cygwin.xsl $< + -$(XMLTO) html -o cygwin-api/ -m $(srcdir)/cygwin.xsl $< cygwin-api/cygwin-api.pdf : cygwin-api.xml fo.xsl - -xsltproc --xinclude $(srcdir)/fo.xsl $< | fop -q -fo - $@ - -cygwin-api.xml : cygwin-api.in.xml doctool Makefile.in - -./doctool -m $(DBXDIRS) -s $(srcdir) -o $@ $< + -$(XSLTPROC) $(srcdir)/fo.xsl $< | fop -q -fo - $@ faq/faq.html : $(FAQ_SOURCES) - -${XMLTO} html -o faq -m $(srcdir)/cygwin.xsl $(srcdir)/faq.xml + -$(XMLTO) html -o faq -m $(srcdir)/cygwin.xsl $(srcdir)/faq.xml -sed -i 's;;;g' faq/faq.html -doctool : doctool.c - gcc -g $< -o $@ - TBFILES = cygwin-ug-net.dvi cygwin-ug-net.rtf cygwin-ug-net.ps \ cygwin-ug-net.pdf cygwin-ug-net.xml \ cygwin-api.dvi cygwin-api.rtf cygwin-api.ps \ @@ -87,7 +78,7 @@ tarball : cygwin-docs.tar.bz2 cygwin-docs.tar.bz2 : $(TBFILES) $(TBDEPS) find $(TBFILES) $(TBDIRS) \! -type d | sort | tar -T - -cf - | bzip2 > cygwin-docs.tar.bz2 -Makefile.dep: cygwin-ug-net.xml +Makefile.dep: cygwin-ug-net.xml cygwin-api.xml cd $(srcdir) && ./xidepend $^ > "${CURDIR}/$@" -include Makefile.dep diff --git a/winsup/doc/cygwin-api.in.xml b/winsup/doc/cygwin-api.in.xml deleted file mode 100644 index 3fee468dc..000000000 --- a/winsup/doc/cygwin-api.in.xml +++ /dev/null @@ -1,34 +0,0 @@ - - - - - - - 1998-08-31 - Cygwin API Reference -DOCTOOL-INSERT-legal - - - - -Compatibility -DOCTOOL-INSERT-std-susv4 -DOCTOOL-INSERT-std-bsd -DOCTOOL-INSERT-std-gnu -DOCTOOL-INSERT-std-solaris -DOCTOOL-INSERT-std-deprec -DOCTOOL-INSERT-std-notimpl -DOCTOOL-INSERT-std-notes - - -Cygwin Functions - -These functions are specific to Cygwin itself, and probably -won't be found anywhere else. - -DOCTOOL-INSERT-func- - - - - diff --git a/winsup/doc/cygwin-api.xml b/winsup/doc/cygwin-api.xml new file mode 100644 index 000000000..a3b9fe102 --- /dev/null +++ b/winsup/doc/cygwin-api.xml @@ -0,0 +1,18 @@ + + + + + + + 1998-08-31 + Cygwin API Reference + + + + + + + + + diff --git a/winsup/doc/doctool.c b/winsup/doc/doctool.c deleted file mode 100644 index 0a5060c76..000000000 --- a/winsup/doc/doctool.c +++ /dev/null @@ -1,622 +0,0 @@ -/* doctool.c - - Copyright 1998,1999,2000,2001,2006 Red Hat, Inc. - -This file is part of Cygwin. - -This software is a copyrighted work licensed under the terms of the -Cygwin license. Please consult the file "CYGWIN_LICENSE" for -details. */ - -#include -#include -#include -#include -#include -#include -#include - -/* Building native in a cross-built directory is tricky. Be careful, -and beware that you don't have the full portability stuff available to -you (like libiberty) */ - -/*****************************************************************************/ - -/* The list of extensions that may contain SGML snippets. We check - both cases in case the file system isn't case sensitive enough. */ - -struct { - char *upper; - char *lower; - int is_sgml; -} extensions[] = { - { ".C", ".c", 0 }, - { ".CC", ".cc", 0 }, - { ".H", ".h", 0 }, - { ".SGML", ".sgml", 1 }, - { 0, 0, 0 } -}; - -/*****************************************************************************/ - -void -show_help() -{ - printf("Usage: doctool [-m] [-i] [-d dir] [-o outfile] [-s prefix] \\\n"); - printf(" [-b book_id] infile\n"); - printf(" -m means to adjust Makefile to include new dependencies\n"); - printf(" -i means to include internal snippets\n"); - printf(" -d means to recursively scan directory for snippets\n"); - printf(" -o means to output to file (else stdout)\n"); - printf(" -s means to suppress source dir prefix\n"); - printf(" -b means to change the \n"); - printf("\n"); - printf("doctool looks for DOCTOOL-START and DOCTOOL-END lines in source,\n"); - printf("saves blocks, and looks for DOCTOOL-INSERT-bar\n"); - printf("commands to insert selected sections. IDs starting with int-\n"); - printf("are internal only, add- are added at the end of relevant sections\n"); - printf("or add-int- for both. Inserted sections are chosen by prefix,\n"); - printf("and sorted when inserted.\n"); - exit(1); -} - -/*****************************************************************************/ - -typedef struct Section { - struct Section *next; - struct OneFile *file; - char *name; - char internal; - char addend; - char used; - char **lines; - int num_lines; - int max_lines; -} Section; - -typedef struct OneFile { - struct OneFile *next; - char *filename; - int enable_scan; - int used; - Section *sections; -} OneFile; - -OneFile *file_list = 0; - -char *output_name = 0; -FILE *output_file = 0; - -char *source_dir_prefix = ""; -char *book_id = 0; - -int internal_flag = 0; - -/*****************************************************************************/ - -char * -has_string(char *line, char *string) -{ - int i; - while (*line) - { - for (i=0; line[i]; i++) - { - if (!string[i]) - return line; - if (line[i] != string[i]) - break; - } - line++; - } - return 0; -} - -int -starts_with(char *line, char *string) -{ - int i=0; - while (1) - { - if (!string[i]) - return 1; - if (!line[i] || line[i] != string[i]) - return 0; - i++; - } -} - -/*****************************************************************************/ - -#ifdef S_ISLNK -#define STAT lstat -#else -#define STAT stat -#endif - -void -scan_directory(dirname) - char *dirname; -{ - struct stat st; - char *name; - struct dirent *de; - DIR *dir = opendir(dirname); - if (!dir) - return; - while (de = readdir(dir)) - { - if (strcmp(de->d_name, ".") == 0 - || strcmp(de->d_name, "..") == 0) - continue; - - name = (char *)malloc(strlen(dirname)+strlen(de->d_name)+3); - strcpy(name, dirname); - strcat(name, "/"); - strcat(name, de->d_name); - - STAT(name, &st); - - if (S_ISDIR(st.st_mode) && strcmp(de->d_name, "CVS") != 0) - { - scan_directory(name); - } - - else if (S_ISREG(st.st_mode)) - { - char *dot = strrchr(de->d_name, '.'); - int i; - - if (dot) - { - for (i=0; extensions[i].upper; i++) - if (strcmp(dot, extensions[i].upper) == 0 - || strcmp(dot, extensions[i].lower) == 0) - { - OneFile *one = (OneFile *)malloc(sizeof(OneFile)); - one->next = file_list; - file_list = one; - one->filename = name; - one->enable_scan = ! extensions[i].is_sgml; - one->used = 0; - one->sections = 0; - } - } - } - } - closedir (dir); -} - -/*****************************************************************************/ - -void -scan_file(OneFile *one) -{ - FILE *f = fopen(one->filename, "r"); - int enabled = ! one->enable_scan; - char line[1000], *tag=0, *id=0, *tmp; - int taglen = 0; - Section *section = 0; - Section **prev_section_ptr = &(one->sections); - - if (!f) - { - perror(one->filename); - return; - } - - while (fgets(line, 1000, f)) - { - if (one->enable_scan) - { - /* source files have comment-embedded docs, check for them */ - if (has_string(line, "DOCTOOL-START")) - enabled = 1; - if (has_string(line, "DOCTOOL-END")) - enabled = 0; - } - if (!enabled) - continue; - - /* DOCTOOL-START - - -this is the doctool tags section. - - - DOCTOOL-END */ - - if (!tag && line[0] == '<') - { - tag = (char *)malloc(strlen(line)+1); - id = (char *)malloc(strlen(line)+1); - if (sscanf(line, "<%s id=\"%[^\"]\">", tag, id) == 2) - { - if (strcmp(tag, "book") == 0 || strcmp(tag, "BOOK") == 0) - { - /* Don't want to "scan" these */ - return; - } - taglen = strlen(tag); - section = (Section *)malloc(sizeof(Section)); - /* We want chunks within single files to appear in that order */ - section->next = 0; - section->file = one; - *prev_section_ptr = section; - prev_section_ptr = &(section->next); - section->internal = 0; - section->addend = 0; - section->used = 0; - section->name = id; - if (starts_with(section->name, "add-")) - { - section->addend = 1; - section->name += 4; - } - if (starts_with(section->name, "int-")) - { - section->internal = 1; - section->name += 4; - } - section->lines = (char **)malloc(10*sizeof(char *)); - section->num_lines = 0; - section->max_lines = 10; - } - else - { - free(tag); - free(id); - tag = id = 0; - } - } - - if (tag && section) - { - if (section->num_lines >= section->max_lines) - { - section->max_lines += 10; - section->lines = (char **)realloc(section->lines, - section->max_lines * sizeof (char *)); - } - section->lines[section->num_lines] = (char *)malloc(strlen(line)+1); - strcpy(section->lines[section->num_lines], line); - section->num_lines++; - - if (line[0] == '<' && line[1] == '/' - && memcmp(line+2, tag, taglen) == 0 - && (isspace(line[2+taglen]) || line[2+taglen] == '>')) - { - /* last line! */ - tag = 0; - } - } - } - fclose(f); -} - -/*****************************************************************************/ - -Section ** -enumerate_matching_sections(char *name_prefix, int internal, int addend, int *count_ret) -{ - Section **rv = (Section **)malloc(12*sizeof(Section *)); - int count = 0, max=10, prefix_len = strlen(name_prefix); - OneFile *one; - int wildcard = 0; - - if (name_prefix[strlen(name_prefix)-1] == '-') - wildcard = 1; - - for (one=file_list; one; one=one->next) - { - Section *s; - for (s=one->sections; s; s=s->next) - { - int matches = 0; - if (wildcard) - { - if (starts_with(s->name, name_prefix)) - matches = 1; - } - else - { - if (strcmp(s->name, name_prefix) == 0) - matches = 1; - } - if (s->internal <= internal - && s->addend == addend - && matches - && ! s->used) - { - s->used = 1; - if (count >= max) - { - max += 10; - rv = (Section **)realloc(rv, max*sizeof(Section *)); - } - rv[count++] = s; - rv[count] = 0; - } - } - } - if (count_ret) - *count_ret = count; - return rv; -} - -/*****************************************************************************/ - -#define ID_CHARS "~@$%&()_-+[]{}:." - -void include_section(char *name, int addend); - -char * -unprefix(char *fn) -{ - int l = strlen(source_dir_prefix); - if (memcmp(fn, source_dir_prefix, l) == 0) - { - fn += l; - while (*fn == '/' || *fn == '\\') - fn++; - return fn; - } - return fn; -} - -void -parse_line(char *line, char *filename) -{ - char *cmd = has_string(line, "DOCTOOL-INSERT-"); - char *sname, *send, *id, *save; - if (!cmd) - { - if (book_id - && (starts_with(line, "'); - if (cmd) - { - cmd++; - fprintf(output_file, "", book_id); - fputs(cmd, output_file); - return; - } - } - fputs(line, output_file); - return; - } - if (cmd != line) - fwrite(line, cmd-line, 1, output_file); - save = (char *)malloc(strlen(line)+1); - strcpy(save, line); - line = save; - - sname = cmd + 15; /* strlen("DOCTOOL-INSERT-") */ - for (send = sname; - *send && isalnum(*send) || strchr(ID_CHARS, *send); - send++); - id = (char *)malloc(send-sname+2); - memcpy(id, sname, send-sname); - id[send-sname] = 0; - include_section(id, 0); - - fprintf(output_file, "\n", unprefix(filename)); - - fputs(send, output_file); - free(save); -} - -int -section_sort(const void *va, const void *vb) -{ - Section *a = *(Section **)va; - Section *b = *(Section **)vb; - int rv = strcmp(a->name, b->name); - if (rv) - return rv; - return a->internal - b->internal; -} - -void -include_section(char *name, int addend) -{ - Section **sections, *s; - int count, i, l; - - sections = enumerate_matching_sections(name, internal_flag, addend, &count); - - qsort(sections, count, sizeof(sections[0]), section_sort); - for (i=0; ifile->used = 1; - fprintf(output_file, "\n", unprefix(s->file->filename)); - for (l=addend; lnum_lines-1; l++) - parse_line(s->lines[l], s->file->filename); - if (!addend) - { - include_section(s->name, 1); - parse_line(s->lines[l], s->file->filename); - } - } - - free(sections); -} - -void -parse_sgml(FILE *in, char *input_name) -{ - static char line[1000]; - while (fgets(line, 1000, in)) - { - parse_line(line, input_name); - } -} - -/*****************************************************************************/ - -void -fix_makefile(char *output_name) -{ - FILE *in, *out; - char line[1000]; - int oname_len = strlen(output_name); - OneFile *one; - int used_something = 0; - struct stat st; - struct utimbuf times; - - stat("Makefile", &st); - - in = fopen("Makefile", "r"); - if (!in) - { - perror("Makefile"); - return; - } - - out = fopen("Makefile.new", "w"); - if (!out) - { - perror("Makefile.new"); - return; - } - - while (fgets(line, 1000, in)) - { - if (starts_with(line, output_name) - && strcmp(line+oname_len, ": \\\n") == 0) - { - /* this is the old dependency */ - while (fgets(line, 1000, in)) - { - if (strcmp(line+strlen(line)-2, "\\\n")) - break; - } - } - else - fputs(line, out); - } - fclose(in); - - for (one=file_list; one; one=one->next) - if (one->used) - { - used_something = 1; - break; - } - - if (used_something) - { - fprintf(out, "%s:", output_name); - for (one=file_list; one; one=one->next) - if (one->used) - fprintf(out, " \\\n\t%s", one->filename); - fprintf(out, "\n"); - } - - fclose(out); - - times.actime = st.st_atime; - times.modtime = st.st_mtime; - utime("Makefile.new", ×); - - if (rename("Makefile", "Makefile.old")) - return; - if (rename("Makefile.new", "Makefile")) - rename("Makefile.old", "Makefile"); -} - -/*****************************************************************************/ - -int -main(argc, argv) - int argc; - char **argv; -{ - int i; - OneFile *one; - FILE *input_file; - int fix_makefile_flag = 0; - - while (argc > 1 && argv[1][0] == '-') - { - if (strcmp(argv[1], "-h") == 0 || strcmp(argv[1], "--help") == 0) - { - show_help(); - } - else if (strcmp(argv[1], "-i") == 0) - { - internal_flag = 1; - } - else if (strcmp(argv[1], "-m") == 0) - { - fix_makefile_flag = 1; - } - else if (strcmp(argv[1], "-d") == 0 && argc > 2) - { - scan_directory(argv[2]); - argc--; - argv++; - } - else if (strcmp(argv[1], "-o") == 0 && argc > 2) - { - output_name = argv[2]; - argc--; - argv++; - } - else if (strcmp(argv[1], "-s") == 0 && argc > 2) - { - source_dir_prefix = argv[2]; - argc--; - argv++; - } - else if (strcmp(argv[1], "-b") == 0 && argc > 2) - { - book_id = argv[2]; - argc--; - argv++; - } - - argc--; - argv++; - } - - for (one=file_list; one; one=one->next) - { - scan_file(one); - } - - input_file = fopen(argv[1], "r"); - if (!input_file) - { - perror(argv[1]); - return 1; - } - - if (output_name) - { - output_file = fopen(output_name, "w"); - if (!output_file) - { - perror(output_name); - return 1; - } - } - else - { - output_file = stdout; - output_name = ""; - } - - parse_sgml(input_file, argv[1]); - - if (output_file != stdout) - fclose(output_file); - - if (fix_makefile_flag) - fix_makefile(output_name); - - return 0; -} diff --git a/winsup/doc/doctool.txt b/winsup/doc/doctool.txt deleted file mode 100644 index c89e39243..000000000 --- a/winsup/doc/doctool.txt +++ /dev/null @@ -1,146 +0,0 @@ -Doctool - -DJ Delorie - -These are the instructions for using doctool. Yes, I should have -written them *in* DocBook, but hey, I was in a hurry. - -OK, doctool is a program that gathers snippets of a docbook document and -puts them all together in the right order. There are three -places that it gets snippets from: - -1. The document that you tell it you want "finished" - -2. blocks of SGML in *.sgml files - -3. comments in source code - -The first of these is the template file, which is to say, it's a -normal SGML file (sort of). This file is the first one read, and -includes such things as your tags etc. It contains commands to -doctool to tell it where to put the other parts. - -The second, the *.sgml files, contain one or more blocks of SGML. -To work with doctool, each of these snippets must begin and end -with matching tags, must have an id="" attribute, and the start/end -tags must begin at the beginning of the line. For example: - - - stuff goes here - - - stuff goes here - - -In this example, the file contains two snippets, one marked by "foo" -and one barked by "bar", with id's "from-45" and "from-48". Note that -I made up the foo and bar tags. You'd usually use a tag or -something useful like that. Stuff outside the blocks is ignored. - -The third is simply an encapsulation of the second in comments, like this: - -/* DOCTOOL-START - - stuff goes here - -DOCTOOL-END */ - -The DOCTOOL-START and DOCTOOL-END things are special. Doctool uses -those to know which parts of which comments are useful, and which -parts are the useless source code stuff ;-) - - -OK, so now we've got all these snippets of SGML floating around. What -do we do with them? Well, inside the template document (#1 in our -list up there) you'd put text snippets that said "ok, put them -here". Each text snippet looks like this: - -DOCTOOL-INSERT-frob- - -Note that the "frob-" part tells doctool to pull in all the snippets -with IDs that start with "frob-", in alphabetical (well, asciibetical -at the moment) order. So, by saying "DOCTOOL-INSERT-frob-" you'd get -all the "frob-*" snippets, like "frob-45" and "frob-48". - -If you just said DOCTOOL-INSERT-frob, it inserts the snippet named -"frob" and no others. - -Note that no snippet will ever be inserted more than once, no matter -how many DOCTOOL-INSERTs you have. - -There's two other tricks doctool has. If it finds a snippet with an ID -like "int-*" (i.e. int-frob-45) that means that snippet of documentation -is for the "internal" version only. The "int-" is discarded, and if -the -i option is given to doctool, this snippet is treated as if the -int- wasn't there. Without the -i, the int-* snippets are ignored -completely. - -If a snippet has "add-" on it, like "add-frob-45", that's an addendum. -Each time a snippet named without the add- is found, doctool looks for -an addendum with exactly that same name (i.e. frob-45 looks for -add-frob-45). If it finds any, it puts them just before the last line -of the non-add snippet (so that it's *inside* the main snippet's -block, not after it). Example: - - - some text - - - more text - - -This would yield: - - - some text - more text - - -You should use the same outermost tags as the main snippet, but only -because it sets the proper nesting rules for what's enclosed. - -You can use add- and int- at the same time, but always do add-int- and -not int-add- (i.e. "add-int-frob-45"). - - -OK, now for doctool command line options. - --m tells doctool to "fix" the Makefile (not makefile) to include the -extra dependencies needed by the file you're generating. You need to -manually include dependencies on the Makefile itself and the template -file; doctool only includes the snippet files (sources etc) that it -actually pulled content from. Note: this isn't perfect! Someone can -come along and add a new snippet to a source file, and doctool would -never know. Sometimes, it's best to just rebuild the docs all the -time. - --i means to include snippets with the "int-" prefix on their IDs. Use -with -b to make internal and public versions from the same sources. - -"-d dir" tells doctool to scan all the files in that directory (and -subdirectories, recursively) for files that might contain snippets of -SGML. These include *.c, *.cc, *.h, and *.sgml. The idea is that -most of the documentation would be in a *.sgml file named after the -source (i.e. foo.c -> foo.sgml) but some commentary within the source -might be useful in the docs as well. SGML files (*.sgml) do not need -the DOCTOOL-START/END tags but the others do. - --o sets the output file. Without -o, the file goes to stdout (ick). - --s tells doctool to supress a "source directory prefix". What this -means is that, in the generated output doctool puts comments that say -where each snippet comes from (for debugging), which includes the full -path sometimes, but if you use -s, you can tell doctool to cut off -that prefix. For example, -/usr/people/dj/src/cygnus/latest/devo/winsup/foo.c might get shortened -to winsup/foo.c if you gave "-s -/usr/people/dj/src/cygnus/latest/devo/". Cygnus makefiles could -just use -s $(srcdir) most of the time. - --b changes the ID for the tag. db2html uses the tag's -ID as the default subdirectory name and/or html file name to create -the book with. You'd need this to generate two books (internal vs -public) from the same source. - -The only other thing you'd add to the command line is the ONE template -file you want to pull in. diff --git a/winsup/doc/faq-programming.xml b/winsup/doc/faq-programming.xml index 47e278220..4332d2b75 100644 --- a/winsup/doc/faq-programming.xml +++ b/winsup/doc/faq-programming.xml @@ -937,8 +937,7 @@ info would not be compatible with gdb). Yes. You can use the strace.exe utility to run other cygwin programs with various debug and trace messages enabled. For information -on using strace, see the Cygwin User's Guide or the file -winsup/utils/utils.sgml in the Cygwin sources. +on using strace, see the Cygwin User's Guide. diff --git a/winsup/doc/path.xml b/winsup/doc/path.xml new file mode 100644 index 000000000..b8cfb920b --- /dev/null +++ b/winsup/doc/path.xml @@ -0,0 +1,190 @@ + + + + +Cygwin Functions + +These functions are specific to Cygwin itself, and probably +won't be found anywhere else. + + +cygwin_conv_path + + +extern "C" ssize_t +cygwin_conv_path +cygwin_conv_path_t what +const void * from +void * to +size_t size + + +Use this function to convert POSIX paths in +from to Win32 paths in to +or, vice versa, Win32 paths in from to POSIX paths +in to. what +defines the direction of this conversion and can be any of the below +values. + + + CCP_POSIX_TO_WIN_A /* from is char *posix, to is char *win32 */ + CCP_POSIX_TO_WIN_W, /* from is char *posix, to is wchar_t *win32 */ + CCP_WIN_A_TO_POSIX, /* from is char *win32, to is char *posix */ + CCP_WIN_W_TO_POSIX, /* from is wchar_t *win32, to is char *posix */ + + +You can additionally or the following values to +what, to define whether you want the resulting +path in to to be absolute or if you want to keep +relative paths in relative notation. Creating absolute paths is the +default. + + + CCP_ABSOLUTE = 0, /* Request absolute path (default). */ + CCP_RELATIVE = 0x100 /* Request to keep path relative. */ + + +size is the size of the buffer pointed to +by to in bytes. If size +is 0, cygwin_conv_path just returns the required +buffer size in bytes. Otherwise, it returns 0 on success, or -1 on +error and errno is set to one of the below values. + + + EINVAL what has an invalid value or from is NULL. + EFAULT from or to point into nirvana. + ENAMETOOLONG the resulting path is longer than 32K, or, in case + of what == CCP_POSIX_TO_WIN_A, longer than MAX_PATH. + ENOSPC size is less than required for the conversion. + + + +Example use of cygwin_conv_path + + + +/* Conversion from incoming Win32 path given as wchar_t *win32 to POSIX path. + If incoming path is a relative path, stick to it. First ask how big + the output buffer has to be and allocate space dynamically. */ +ssize_t size; +char *posix; +size = cygwin_conv_path (CCP_WIN_W_TO_POSIX | CCP_RELATIVE, win32, NULL, 0); +if (size < 0) + perror ("cygwin_conv_path"); +else + { + posix = (char *) malloc (size); + if (cygwin_conv_path (CCP_WIN_W_TO_POSIX | CCP_RELATIVE, win32, + posix, size)) + perror ("cygwin_conv_path"); + } +]]> + + + + + + +cygwin_conv_path_list + + +extern "C" ssize_t +cygwin_conv_path_list +cygwin_conv_path_t what +const void * from +void * to +size_t size + + +This is the same as cygwin_conv_path, but the +input is treated as a path list in $PATH or %PATH% notation. +If what is CCP_POSIX_TO_WIN_A or +CCP_POSIX_TO_WIN_W, given a POSIX $PATH-style string (i.e. /foo:/bar) +convert it to the equivalent Win32 %PATH%-style string (i.e. d:\;e:\bar). +If what is CCP_WIN_A_TO_POSIX or +CCP_WIN_W_TO_POSIX, given a Win32 %PATH%-style string (i.e. d:\;e:\bar) +convert it to the equivalent POSIX $PATH-style string (i.e. /foo:/bar). +size is the size of the buffer pointed to by +to in bytes. + +See also cygwin_conv_path + + + + +cygwin_create_path + + +extern "C" void * +cygwin_create_path +cygwin_conv_path_t what +const void * from + + +This is equivalent to the cygwin_conv_path, except +that cygwin_create_path does not take a buffer pointer +for the result of the conversion as input. Rather it allocates the buffer +itself using malloc(3) and returns a pointer to this +buffer. In case of error it returns NULL and sets errno to one of the +values defined for cygwin_conv_path. Additionally +errno can be set to the below value. + + + ENOMEM Insufficient memory was available. + + +When you don't need the returned buffer anymore, use +free(3) to deallocate it. + +See also cygwin_conv_path + + + + +cygwin_posix_path_list_p + + +extern "C" int +cygwin_posix_path_list_p +const char *path + + +This function tells you if the supplied +path is a POSIX-style path (i.e. posix names, +forward slashes, colon delimiters) or a Win32-style path (drive +letters, reverse slashes, semicolon delimiters. The return value is +true if the path is a POSIX path. Note that "_p" means "predicate", a +lisp term meaning that the function tells you something about the +parameter. + + + + +cygwin_split_path + + +extern "C" void +cygwin_split_path + +const char * path +char * dir +char * file + + +Split a path into the directory and the file portions. Both +dir and file are +expected to point to buffers of sufficient size. + + +Example use of cygwin_split_path + +char dir[200], file[100]; +cygwin_split_path("c:/foo/bar.c", dir, file); +printf("dir=%s, file=%s\n", dir, file); + + + + + diff --git a/winsup/doc/posix.xml b/winsup/doc/posix.xml new file mode 100644 index 000000000..d30d23ad7 --- /dev/null +++ b/winsup/doc/posix.xml @@ -0,0 +1,1565 @@ + + + + +Compatibility + +System interfaces compatible with the Single Unix Specification, Version 4: + +Note that the core of the Single Unix Specification, Version 4 is +also IEEE Std 1003.1-2008 (POSIX.1-2008). + + + FD_CLR + FD_ISSET + FD_SET + FD_ZERO + _Exit + _exit + _longjmp + _setjmp + _tolower + _toupper + a64l + abort + abs + accept + access + acos + acosf + acosh + acoshf + alarm + alphasort + asctime + asctime_r + asin + asinf + asinh + asinhf + atan + atan2 + atan2f + atanf + atanh + atanhf + atexit + atof + atoff + atoi + atol + atoll + basename + bind + bsearch + btowc + cabs + cabsf + cacos + cacosf + cacosh + cacoshf + calloc + carg + cargf + casin + casinf + casinh + casinhf + casinhl + catan + catanf + catanh + catanhf + catclose (available in external "catgets" library) + catgets (available in external "catgets" library) + catopen (available in external "catgets" library) + cbrt + cbrtf + ccos + ccosf + ccosh + ccoshf + ceil + ceilf + cexp + cexpf + cfgetispeed + cfgetospeed + cfsetispeed + cfsetospeed + chdir + chmod + chown + cimag + cimagf + clearerr + clock + clock_getcpuclockid + clock_getres + clock_gettime + clock_nanosleep (see chapter "Implementation Notes") + clock_settime (see chapter "Implementation Notes") + clog + clogf + close + closedir + closelog + confstr + conj + conjf + connect + copysign + copysignf + cos + cosf + cosh + coshf + cpow + cpowf + cproj + cprojf + creal + crealf + creat + crypt (available in external "crypt" library) + csin + csinf + csinh + csinhf + csqrt + csqrtf + ctan + ctanf + ctanh + ctanhf + ctermid + ctime + ctime_r + daylight + dbm_clearerr (available in external "libgdbm" library) + dbm_close (available in external "libgdbm" library) + dbm_delete (available in external "libgdbm" library) + dbm_error (available in external "libgdbm" library) + dbm_fetch (available in external "libgdbm" library) + dbm_firstkey (available in external "libgdbm" library) + dbm_nextkey (available in external "libgdbm" library) + dbm_open (available in external "libgdbm" library) + dbm_store (available in external "libgdbm" library) + difftime + dirfd + dirname + div + dlclose + dlerror + dlopen + dlsym + dprintf + drand48 + dup + dup2 + encrypt (available in external "crypt" library) + endgrent + endhostent + endprotoent + endpwent + endservent + endutxent + environ + erand48 + erf + erfc + erfcf + erff + errno + execl + execle + execlp + execv + execve + execvp + exit + exp + exp2 + exp2f + expf + expm1 + expm1f + fabs + fabsf + faccessat + fchdir + fchmod + fchmodat + fchown + fchownat + fclose + fcntl (see chapter "Implementation Notes") + fdatasync + fdim + fdimf + fdopen + fdopendir + feclearexcept + fegetenv + fegetexceptflag + fegetround + feholdexcept + feof + feraiseexcept + ferror + fesetenv + fesetexceptflag + fesetround + fetestexcept + feupdateenv + fexecve + fflush + ffs + fgetc + fgetpos + fgets + fgetwc + fgetws + fileno + flockfile + floor + floorf + fma + fmaf + fmax + fmaxf + fmemopen + fmin + fminf + fmod + fmodf + fnmatch + fopen + fork + fpathconf + fpclassify (see chapter "Implementation Notes") + fprintf + fputc + fputs + fputwc + fputws + fread + free + freeaddrinfo + freopen + frexp + frexpf + fscanf + fseek + fseeko + fsetpos + fstat + fstatat + fstatvfs + fsync + ftell + ftello + ftok + ftruncate + ftrylockfile + ftw + funlockfile + futimens + fwide + fwprintf + fwrite + fwscanf + gai_strerror + getaddrinfo + getc + getc_unlocked + getchar + getchar_unlocked + getcwd + getdelim + getdomainname + getegid + getenv + geteuid + getgid + getgrent + getgrgid + getgrgid_r + getgrnam + getgrnam_r + getgroups + gethostid + gethostname + getitimer (see chapter "Implementation Notes") + getline + getlogin + getlogin_r + getnameinfo + getopt + getpeername + getpgid + getpgrp + getpid + getppid + getpriority + getprotobyname + getprotobynumber + getprotoent + getpwent + getpwnam + getpwnam_r + getpwuid + getpwuid_r + getrlimit + getrusage + gets + getservbyname + getservbyport + getservent + getsid + getsockname + getsockopt + getsubopt + gettimeofday + getuid + getutxent + getutxid + getutxline + getwc + getwchar + glob + globfree + gmtime + gmtime_r + grantpt + hcreate + hdestroy + hsearch + htonl + htons + hypot + hypotf + iconv (available in external "libiconv" library) + iconv_close (available in external "libiconv" library) + iconv_open (available in external "libiconv" library) + if_freenameindex + if_indextoname + if_nameindex + if_nametoindex + ilogb + ilogbf + imaxabs + imaxdiv + inet_addr + inet_ntoa + inet_ntop + inet_pton + initstate + insque + ioctl + isalnum + isalpha + isascii + isatty + isblank + iscntrl + isdigit + isfinite (see chapter "Implementation Notes") + isgraph + isgreater (see chapter "Implementation Notes") + isgreaterequal (see chapter "Implementation Notes") + isinf (see chapter "Implementation Notes") + isless + islessequal (see chapter "Implementation Notes") + islessgreater (see chapter "Implementation Notes") + islower + isnan (see chapter "Implementation Notes") + isnormal (see chapter "Implementation Notes") + isprint + ispunct + isspace + isunordered (see chapter "Implementation Notes") + isupper + iswalnum + iswalpha + iswblank + iswcntrl + iswctype + iswdigit + iswgraph + iswlower + iswprint + iswpunct + iswspace + iswupper + iswxdigit + isxdigit + j0 + j1 + jn + jrand48 + kill + killpg + l64a + labs + lchown + lcong48 + ldexp + ldexpf + ldiv + lfind + lgamma + lgammaf + link + linkat + listen + llabs + lldiv + llrint + llrintf + llrintl + llround + llroundf + localeconv + localtime + localtime_r + lockf (see chapter "Implementation Notes") + log + log10 + log10f + log1p + log1pf + log2 + log2f + logb + logbf + logf + longjmp + lrand48 + lrint + lrintf + lrintl + lround + lroundf + lsearch + lseek + lstat + malloc + mblen + mbrlen + mbrtowc + mbsinit + mbsnrtowcs + mbsrtowcs + mbstowcs + mbtowc + memccpy + memchr + memcmp + memcpy + memmove + memset + mkdir + mkdirat + mkdtemp + mkfifo + mkfifoat + mknod + mknodat + mkstemp + mktime + mlock + mmap + modf + modff + mprotect + mq_close + mq_getattr + mq_notify + mq_open + mq_receive + mq_send + mq_setattr + mq_timedreceive + mq_timedsend + mq_unlink + mrand48 + msgctl (see chapter "Implementation Notes") + msgget (see chapter "Implementation Notes") + msgrcv (see chapter "Implementation Notes") + msgsnd (see chapter "Implementation Notes") + msync + munlock + munmap + nan + nanf + nanosleep + nearbyint + nearbyintf + nextafter + nextafterf + nftw + nice + nl_langinfo + nrand48 + ntohl + ntohs + open + open_memstream + open_wmemstream + openat + opendir + openlog + optarg + opterr + optind + optopt + pathconf + pause + pclose + perror + pipe + poll + popen + posix_fadvise + posix_fallocate + posix_madvise + posix_memalign + posix_openpt + posix_spawn + posix_spawnattr_destroy + posix_spawnattr_init + posix_spawnattr_getflags + posix_spawnattr_getpgroup + posix_spawnattr_getschedparam + posix_spawnattr_getschedpolicy + posix_spawnattr_getsigdefault + posix_spawnattr_getsigmask + posix_spawnattr_setflags + posix_spawnattr_setpgroup + posix_spawnattr_setschedparam + posix_spawnattr_setschedpolicy + posix_spawnattr_setsigdefault + posix_spawnattr_setsigmask + posix_spawnp + posix_spawn_file_actions_destroy + posix_spawn_file_actions_init + posix_spawn_file_actions_addclose + posix_spawn_file_actions_adddup2 + posix_spawn_file_actions_addopen + pow + powf + pread + printf + pselect + psiginfo + psignal + pthread_atfork + pthread_attr_destroy + pthread_attr_getdetachstate + pthread_attr_getguardsize + pthread_attr_getinheritsched + pthread_attr_getschedparam + pthread_attr_getschedpolicy + pthread_attr_getscope + pthread_attr_getstack + pthread_attr_getstacksize + pthread_attr_init + pthread_attr_setdetachstate + pthread_attr_setguardsize + pthread_attr_setinheritsched + pthread_attr_setschedparam + pthread_attr_setschedpolicy + pthread_attr_setscope + pthread_attr_setstack + pthread_attr_setstacksize + pthread_cancel + pthread_cond_broadcast + pthread_cond_destroy + pthread_cond_init + pthread_cond_signal + pthread_cond_timedwait + pthread_cond_wait + pthread_condattr_destroy + pthread_condattr_getclock + pthread_condattr_getpshared + pthread_condattr_init + pthread_condattr_setclock + pthread_condattr_setpshared + pthread_create + pthread_detach + pthread_equal + pthread_exit + pthread_getconcurrency + pthread_getcpuclockid + pthread_getschedparam + pthread_getspecific + pthread_join + pthread_key_create + pthread_key_delete + pthread_kill + pthread_mutex_destroy + pthread_mutex_getprioceiling + pthread_mutex_init + pthread_mutex_lock + pthread_mutex_setprioceiling + pthread_mutex_trylock + pthread_mutex_unlock + pthread_mutexattr_destroy + pthread_mutexattr_getprioceiling + pthread_mutexattr_getprotocol + pthread_mutexattr_getpshared + pthread_mutexattr_gettype + pthread_mutexattr_init + pthread_mutexattr_setprioceiling + pthread_mutexattr_setprotocol + pthread_mutexattr_setpshared + pthread_mutexattr_settype + pthread_once + pthread_rwlock_destroy + pthread_rwlock_init + pthread_rwlock_rdlock + pthread_rwlock_tryrdlock + pthread_rwlock_trywrlock + pthread_rwlock_unlock + pthread_rwlock_wrlock + pthread_rwlockattr_destroy + pthread_rwlockattr_getpshared + pthread_rwlockattr_init + pthread_rwlockattr_setpshared + pthread_self + pthread_setcancelstate + pthread_setcanceltype + pthread_setconcurrency + pthread_setschedparam + pthread_setschedprio + pthread_setspecific + pthread_sigmask + pthread_spin_destroy + pthread_spin_init + pthread_spin_lock + pthread_spin_trylock + pthread_spin_unlock + pthread_testcancel + ptsname + putc + putc_unlocked + putchar + putchar_unlocked + putenv + puts + pututxline + putwc + putwchar + pwrite + qsort + raise + rand + rand_r + random + read + readdir + readdir_r + readlink + readlinkat + readv + realloc + realpath + recv + recvfrom + recvmsg + regcomp + regerror + regexec + regfree + remainder + remainderf + remove + remque + remquo + remquof + rename + renameat + rewind + rewinddir + rint + rintf + rintl + rmdir + round + roundf + scalbln + scalblnf + scalbn + scalbnf + scandir + scanf + sched_get_priority_max + sched_get_priority_min + sched_getparam + sched_getscheduler + sched_rr_get_interval + sched_setparam + sched_setscheduler + sched_yield + seed48 + seekdir + select + sem_close + sem_destroy + sem_getvalue + sem_init + sem_open + sem_post + sem_timedwait + sem_trywait + sem_unlink + sem_wait + semctl (see chapter "Implementation Notes") + semget (see chapter "Implementation Notes") + semop (see chapter "Implementation Notes") + send + sendmsg + sendto + setbuf + setegid + setenv + seteuid + setgid + setgrent + sethostent + setitimer (see chapter "Implementation Notes") + setjmp + setkey (available in external "crypt" library) + setlocale + setlogmask + setpgid + setpgrp + setpriority + setprotoent + setpwent + setregid + setreuid + setrlimit + setservent + setsid + setsockopt + setstate + setuid + setutxent + setvbuf + shm_open + shm_unlink + shmat (see chapter "Implementation Notes") + shmctl (see chapter "Implementation Notes") + shmdt (see chapter "Implementation Notes") + shmget (see chapter "Implementation Notes") + shutdown + sigaction + sigaddset + sigdelset + sigemptyset + sigfillset + sighold + sigignore + siginterrupt + sigismember + siglongjmp + signal + signbit (see chapter "Implementation Notes") + signgam + sigpause + sigpending + sigprocmask + sigqueue + sigrelse + sigset + sigsetjmp + sigsuspend + sigwait + sigwaitinfo + sin + sinf + sinh + sinhf + sleep + snprintf + socket + socketpair + sprintf + sqrt + sqrtf + srand + srand48 + srandom + sscanf + stat + statvfs + stderr + stdin + stdout + stpcpy + stpncpy + strcasecmp + strcat + strchr + strcmp + strcoll + strcpy + strcspn + strdup + strerror + strerror_r + strfmon + strftime + strlen + strncasecmp + strncat + strncmp + strncpy + strndup + strnlen + strpbrk + strptime + strrchr + strsignal + strspn + strstr + strtod + strtof + strtoimax + strtok + strtok_r + strtol + strtoll + strtoul + strtoull + strtoumax + strxfrm + swab + swprintf + swscanf + symlink + symlinkat + sync + sysconf + syslog + system + tan + tanf + tanh + tanhf + tcdrain + tcflow + tcflush + tcgetattr + tcgetpgrp + tcsendbreak + tcsetattr + tcsetpgrp + tdelete + telldir + tempnam + tfind + tgamma + tgammaf + time + timer_create (see chapter "Implementation Notes") + timer_delete + timer_gettime + timer_settime + times + timezone + tmpfile + tmpnam + toascii + tolower + toupper + towctrans + towlower + towupper + trunc + truncate + truncf + tsearch + ttyname + ttyname_r + twalk + tzname + tzset + umask + uname + ungetc + ungetwc + unlink + unlinkat + unlockpt + unsetenv + utime + utimensat + utimes + va_arg + va_copy + va_end + va_start + vdprintf + vfprintf + vfscanf + vfwprintf + vfwscanf + vprintf + vscanf + vsnprintf + vsprintf + vsscanf + vswprintf + vswscanf + vwprintf + vwscanf + wait + waitpid + wcpcpy + wcpncpy + wcrtomb + wcscasecmp + wcscat + wcschr + wcscmp + wcscoll + wcscpy + wcscspn + wcsdup + wcsftime + wcslen + wcsncasecmp + wcsncat + wcsncmp + wcsncpy + wcsnlen + wcsnrtombs + wcspbrk + wcsrchr + wcsrtombs + wcsspn + wcsstr + wcstod + wcstof + wcstoimax + wcstok + wcstol + wcstoll + wcstombs + wcstoul + wcstoull + wcstoumax + wcswidth + wcsxfrm + wctob + wctomb + wctrans + wctype + wcwidth + wmemchr + wmemcmp + wmemcpy + wmemmove + wmemset + wordexp + wordfree + wprintf + write + writev + wscanf + y0 + y1 + yn + + + + +System interfaces compatible with BSD functions: + + + __b64_ntop + __b64_pton + arc4random + arc4random_addrandom + arc4random_buf + arc4random_stir + arc4random_uniform + bindresvport + bindresvport_sa + cfmakeraw + cfsetspeed + daemon + dn_comp + dn_expand + dn_skipname + drem + eaccess + endusershell + err + errx + finite + finitef + fiprintf + flock (see chapter "Implementation Notes") + forkpty + fpurge + freeifaddrs + fstatfs + fts_children + fts_close + fts_get_clientptr + fts_get_stream + fts_open + fts_read + fts_set + fts_set_clientptr + funopen + futimes + gamma + gamma_r + gammaf + gammaf_r + getdtablesize + getgrouplist + getifaddrs + getpagesize + getpeereid + getprogname + getusershell + herror + hstrerror + inet_aton + inet_makeaddr + inet_netof + inet_network + initgroups + iruserok + iruserok_sa + login + login_tty + logout + logwtmp + madvise + mkstemps + openpty + rcmd + rcmd_af + reallocf + res_close + res_init + res_mkquery + res_nclose + res_ninit + res_nmkquery + res_nquery + res_nquerydomain + res_nsearch + res_nsend + res_query + res_querydomain + res_search + res_send + revoke + rexec + rresvport + rresvport_af + ruserok + sbrk + setbuffer + setgroups + setlinebuf + setpassent + setprogname + settimeofday + setusershell + statfs + strcasestr + strlcat + strlcpy + strsep + updwtmp + valloc + verr + verrx + vhangup (see chapter "Implementation Notes") + vsyslog + vwarn + vwarnx + wait3 + wait4 + warn + warnx + wcslcat + wcslcpy + + + + +System interfaces compatible with GNU or Linux extensions: + + + accept4 + argz_add + argz_add_sep + argz_append + argz_count + argz_create + argz_create_sep + argz_delete + argz_extract + argz_insert + argz_next + argz_replace + argz_stringify + asnprintf + asprintf + asprintf_r + canonicalize_file_name + dremf + dup3 + envz_add + envz_entry + envz_get + envz_merge + envz_remove + envz_strip + error + error_at_line + euidaccess + execvpe + exp10 + exp10f + fcloseall + fcloseall_r + fegetprec + fesetprec + feenableexcept + fedisableexcept + fegetexcept + fgetxattr + flistxattr + fopencookie + fremovexattr + fsetxattr + get_avphys_pages + get_current_dir_name + get_phys_pages + get_nprocs + get_nprocs_conf + getmntent_r + getopt_long + getopt_long_only + getpt + getxattr + lgetxattr + listxattr + llistxattr + lremovexattr + lsetxattr + memmem + mempcpy + memrchr + mkostemp + mkostemps + pipe2 + pow10 + pow10f + ppoll + pthread_getattr_np + pthread_sigqueue + ptsname_r + rawmemchr + removexattr + scandirat + setxattr + strchrnul + sysinfo + tdestroy + timegm + timelocal + updwtmpx + utmpxname + vasnprintf + vasprintf + vasprintf_r + + + + +System interfaces compatible with Solaris or SunOS functions: + + + __fpurge + acl + aclcheck + aclfrommode + aclfrompbits + aclfromtext + aclsort + acltomode + acltopbits + acltotext + endmntent + facl + futimesat + getmntent + memalign + setmntent + xdr_array + xdr_bool + xdr_bytes + xdr_char + xdr_double + xdr_enum + xdr_float + xdr_free + xdr_hyper + xdr_int + xdr_int16_t + xdr_int32_t + xdr_int64_t + xdr_int8_t + xdr_long + xdr_longlong_t + xdr_netobj + xdr_opaque + xdr_pointer + xdr_reference + xdr_short + xdr_sizeof + xdr_string + xdr_u_char + xdr_u_hyper + xdr_u_int + xdr_u_int16_t + xdr_u_int32_t + xdr_u_int64_t + xdr_u_int8_t + xdr_u_long + xdr_u_longlong_t + xdr_u_short + xdr_uint16_t + xdr_uint32_t + xdr_uint64_t + xdr_uint8_t + xdr_union + xdr_vector + xdr_void + xdr_wrapstring + xdrmem_create + xdrrec_create + xdrrec_endofrecord + xdrrec_eof + xdrrec_skiprecord + __xdrrec_getrec + __xdrrec_setnonblock + xdrstdio_create + + + + +Other UNIX system interfaces, deprecated or not in POSIX.1-2008: + + + bcmp (POSIX.1-2001, SUSv3) + bcopy (SUSv3) + bzero (SUSv3) + chroot (SUSv2) (see chapter "Implementation Notes") + clock_setres (QNX, VxWorks) (see chapter "Implementation Notes") + cuserid (POSIX.1-1988, SUSv2) + ecvt (SUSv3) + endutent (XPG2) + fcvt (SUSv3) + ftime (SUSv3) + gcvt (SUSv3) + gethostbyaddr (SUSv3) + gethostbyname (SUSv3) + gethostbyname2 (first defined in BIND 4.9.4) + getpass (SUSv2) + getutent (XPG2) + getutid (XPG2) + getutline (XPG2) + getw (SVID) + getwd (SUSv3) + h_errno (SUSv3) + index (SUSv3) + mallinfo (SVID) + mallopt (SVID) + mktemp (SUSv3) + on_exit (SunOS) + pthread_attr_getstackaddr (SUSv3) + pthread_attr_setstackaddr (SUSv3) + pthread_continue (XPG2) + pthread_getsequence_np (Tru64) + pthread_suspend (XPG2) + pthread_yield (POSIX.1c drafts) + pututline (XPG2) + putw (SVID) + rindex (SUSv3) + scalb (SUSv3) + setutent (XPG2) + sys_errlist (BSD) + sys_nerr (BSD) + sys_siglist (BSD) + ttyslot (SUSv2) + ualarm (SUSv3) + usleep (SUSv3) + utmpname (XPG2) + vfork (SUSv3) (see chapter "Implementation Notes") + + + + +NOT implemented system interfaces from the Single Unix Specification, Volume 4: + + + acoshl + acosl + aio_cancel + aio_error + aio_fsync + aio_read + aio_return + aio_suspend + aio_write + asinhl + asinl + atan2l + atanhl + atanl + cabsl + cacoshl + cacosl + cargl + casinl + catanhl + catanl + cbrtl + ccoshl + ccosl + ceill + cexpl + cimagl + clogl + conjl + copysignl + coshl + cosl + cpowl + cprojl + creall + csinhl + csinl + csqrtl + ctanhl + ctanl + duplocale + endnetent + erfcl + erfl + exp2l + expl + expm1l + fabsl + fattach + fdiml + floorl + fmal + fmaxl + fminl + fmodl + fmtmsg + freelocale + frexpl + getdate + getdate_err + gethostent + getmsg + getnetbyaddr + getnetbyname + getnetent + getpmsg + hypotl + ilogbl + isalnum_l + isalpha_l + isastream + isblank_l + iscntrl_l + isdigit_l + isgraph_l + islower_l + isprint_l + ispunct_l + isspace_l + isupper_l + iswalnum_l + iswalpha_l + iswblank_l + iswcntrl_l + iswdigit_l + iswgraph_l + iswlower_l + iswprint_l + iswpunct_l + iswspace_l + iswupper_l + iswxdigit_l + isxdigit_l + ldexpl + lgammal + lio_listio + llroundl + log10l + log1pl + log2l + logbl + logl + lroundl + mlockall + modfl + munlockall + nanl + nearbyintl + newlocale + nextafterl + nexttoward + nexttowardf + nexttowardl + posix_mem_offset + posix_trace[...] + posix_typed_[...] + powl + pthread_barrier[...] + pthread_mutexattr_getrobust + pthread_mutexattr_setrobust + pthread_mutex_consistent + pthread_mutex_timedlock + pthread_rwlock_timedrdlock + pthread_rwlock_timedwrlock + putmsg + reminderl + remquol + roundl + scalblnl + scalbnl + setnetent + sigaltstack + sigtimedwait + sinhl + sinl + sockatmark + sqrtl + strcasecmp_l + strcoll_l + strfmon_l + strncasecmp_l + strtold + strxfrm_l + tanhl + tanl + tcgetsid + tgammal + timer_getoverrun + tolower_l + toupper_l + towctrans_l + truncl + ulimit + uselocale + waitid + wcscasecmp_l + wcsncasecmp_l + wcstold + wcsxfrm_l + wctrans_l + wctype_l + + + + +Implementation Notes + +chroot only emulates a chroot function call +by keeping track of the current root and accomodating this in the file +related function calls. A real chroot functionality is not supported by +Windows however. + +clock_nanosleep currently supports only +CLOCK_REALTIME and CLOCK_MONOTONIC. clock_setres, +clock_settime, and timer_create +currently support only CLOCK_REALTIME. + +POSIX file locks via fcntl or +lockf, as well as BSD flock locks +are advisory locks. They don't interact with Windows mandatory locks, nor +do POSIX fcntl locks interfere with BSD flock locks or vice versa. + +BSD file locks created via flock are only +propagated to the direct parent process, not to grand parents or sibling +processes. The locks are only valid in the creating process, its parent +process, and subsequently started child processes sharing the same file +descriptor. + +In very rare circumstances an application would want to use Windows +mandatory locks to interact with non-Cygwin Windows processes accessing the +same file (databases, etc). For these purposes, the entire locking mechanism +(fcntl/flock/lockf) can be switched to Windows mandatory locks on a +per-descriptor/per-process basis. For this purpose, use the call + + + fcntl (fd, F_LCK_MANDATORY, 1); + + +After that, all file locks on this descriptor will follow Windows mandatory +record locking semantics: Locks are per-descriptor/per-process; locks are not +propagated to child processes, not even via execve; +no atomic replacement of read locks with write locks and vice versa on the +same descriptor; locks have to be unlocked exactly as they have been locked. + + +fpclassify, isfinite, +isgreater, isgreaterequal, +isinf, isless, +islessequal, islessgreater, +isnan, isnormal, +isunordered, and signbit +only support float and double arguments, not long double arguments. + +getitimer and setitimer +only support ITIMER_REAL for now. + +link will fail on FAT, FAT32, and other filesystems +not supporting hardlinks, just as on Linux. + +lseek only works properly on files opened in +binary mode. On files opened in textmode (via mount mode or explicit +open flag) its positioning is potentially unreliable. + +setuid is only safe against reverting the user +switch after a call to one of the exec(2) functions took place. Windows +doesn't support a non-revertable user switch within the context of Win32 +processes. + +vfork just calls fork. + +vhangup and revoke always +return -1 and set errno to ENOSYS. grantpt and +unlockpt always just return 0. + +The XSI IPC functions semctl, +semget, semop, +shmat, shmctl, +shmdt, shmget, +msgctl, msgget, +msgrcv and msgsnd are only +available when cygserver is running. + + + + diff --git a/winsup/doc/using.xml b/winsup/doc/using.xml index 1795acccd..3ec26707b 100644 --- a/winsup/doc/using.xml +++ b/winsup/doc/using.xml @@ -16,6 +16,6 @@ knowledge of standard UNIX commands. - + diff --git a/winsup/doc/utils.xml b/winsup/doc/utils.xml new file mode 100644 index 000000000..42faa260d --- /dev/null +++ b/winsup/doc/utils.xml @@ -0,0 +1,2104 @@ + + + + + Cygwin Utilities + + Cygwin comes with a number of command-line utilities that are used to + manage the UNIX emulation portion of the Cygwin environment. While many of + these reflect their UNIX counterparts, each was written specifically for + Cygwin. You may use the long or short option names interchangeably; for + example, --help and -h function + identically. All of the Cygwin command-line utilities support the + --help and --version options. + + + cygcheck + + +Usage: cygcheck [-v] [-h] PROGRAM + cygcheck -c [-d] [PACKAGE] + cygcheck -s [-r] [-v] [-h] + cygcheck -k + cygcheck -f FILE [FILE]... + cygcheck -l [PACKAGE]... + cygcheck -p REGEXP + cygcheck --delete-orphaned-installation-keys + cygcheck --enable-unique-object-names Cygwin-DLL + cygcheck --disable-unique-object-names Cygwin-DLL + cygcheck --show-unique-object-names Cygwin-DLL + cygcheck -h + +List system information, check installed packages, or query package database. + +At least one command option or a PROGRAM is required, as shown above. + + PROGRAM list library (DLL) dependencies of PROGRAM + -c, --check-setup show installed version of PACKAGE and verify integrity + (or for all installed packages if none specified) + -d, --dump-only just list packages, do not verify (with -c) + -s, --sysinfo produce diagnostic system information (implies -c -d) + -r, --registry also scan registry for Cygwin settings (with -s) + -k, --keycheck perform a keyboard check session (must be run from a + plain console only, not from a pty/rxvt/xterm) + -f, --find-package find the package to which FILE belongs + -l, --list-package list contents of PACKAGE (or all packages if none given) + -p, --package-query search for REGEXP in the entire cygwin.com package + repository (requires internet connectivity) + --delete-orphaned-installation-keys + Delete installation keys of old, now unused + installations from the registry. Requires the right + to change the registry. + --enable-unique-object-names Cygwin-DLL + --disable-unique-object-names Cygwin-DLL + --show-unique-object-names Cygwin-DLL + Enable, disable, or show the setting of the + \"unique object names\" setting in the Cygwin DLL + given as argument to this option. The DLL path must + be given as valid Windows(!) path. + See the users guide for more information. + If you don't know what this means, don't change it. + -v, --verbose produce more verbose output + -h, --help annotate output with explanatory comments when given + with another command, otherwise print this help + -V, --version print the version of cygcheck and exit + +Note: -c, -f, and -l only report on packages that are currently installed. To + search all official Cygwin packages use -p instead. The -p REGEXP matches + package names, descriptions, and names of files/paths within all packages. + + + The cygcheck program is a diagnostic utility for + dealing with Cygwin programs. If you are familiar with + dpkg or rpm, + cygcheck is similar in many ways. (The major + difference is that setup.exe handles installing and + uninstalling packages; see for more + information.) + The -c option checks the version and status of + installed Cygwin packages. If you specify one or more package names, + cygcheck will limit its output to those packages, or + with no arguments it lists all packages. A package will be marked + Incomplete if files originally installed are no longer + present. The best thing to do in that situation is reinstall the package + with setup.exe. To see which files are missing, use + the -v option. If you do not need to know the status + of each package and want cygcheck to run faster, add + the -d option and cygcheck will + only output the name and version for each package. + If you list one or more programs on the command line, + cygcheck will diagnose the runtime environment of that + program or programs, providing the names of DLL files on which the + program depends. If you specify the -s option, + cygcheck will give general system information. If you + list one or more programs on the command line and specify + -s, cygcheck will report on + both. + The -f option helps you to track down which + package a file came from, and -l lists all files in a + package. For example, to find out about + /usr/bin/less and its package: Example <command>cygcheck</command> + usage + +$ cygcheck -f /usr/bin/less +less-381-1 + +$ cygcheck -l less +/usr/bin/less.exe +/usr/bin/lessecho.exe +/usr/bin/lesskey.exe +/usr/man/man1/less.1 +/usr/man/man1/lesskey.1 + + + + The -h option prints additional helpful messages + in the report, at the beginning of each section. It also adds table + column headings. While this is useful information, it also adds some to + the size of the report, so if you want a compact report or if you know + what everything is already, just leave this out. + + The -v option causes the output to be more + verbose. What this means is that additional information will be reported + which is usually not interesting, such as the internal version numbers of + DLLs, additional information about recursive DLL usage, and if a file in + one directory in the PATH also occurs in other directories on the PATH. + + The -r option causes cygcheck + to search your registry for information that is relevant to Cygwin + programs. These registry entries are the ones that have "Cygwin" in the + name. If you are paranoid about privacy, you may remove information from + this report, but please keep in mind that doing so makes it harder to + diagnose your problems. + + In contrast to the other options that search the packages that are + installed on your local system, the -p option can be + used to search the entire official Cygwin package repository. It takes as + argument a Perl-compatible regular expression which is used to match + package names, package descriptions, and path/filenames of the contents + of packages. This feature requires an active internet connection, since + it must query the cygwin.com web site. In fact, it is + equivalent to the search that is available on the Cygwin package listing + page. + + For example, perhaps you are getting an error because you are missing + a certain DLL and you want to know which package includes that file: + Searching all packages for a + file + +$ cygcheck -p 'cygintl-2\.dll' +Found 1 matches for 'cygintl-2\.dll'. + +libintl2-0.12.1-3 GNU Internationalization runtime library + +$ cygcheck -p 'libexpat.*\.a' +Found 2 matches for 'libexpat.*\.a'. + +expat-1.95.7-1 XML parser library written in C +expat-1.95.8-1 XML parser library written in C + +$ cygcheck -p '/ls\.exe' +Found 2 matches for '/ls\.exe'. + +coreutils-5.2.1-5 GNU core utilities (includes fileutils, sh-utils and textutils) +coreutils-5.3.0-6 GNU core utilities (includes fileutils, sh-utils and textutils) + + + + Note that this option takes a regular expression, not a glob or + wildcard. This means that you need to use .* if you + want something similar to the wildcard * commonly used + in filename globbing. Similarly, to match the period character you should + use \. since the . character in a + regexp is a metacharacter that will match any character. Also be aware + that the characters such as \ and * + are shell metacharacters, so they must be either escaped or quoted, as in + the example above. + + The third example above illustrates that if you want to match a whole + filename, you should include the / path seperator. In + the given example this ensures that filenames that happen to end in + ls.exe such as ncftpls.exe are not + shown. Note that this use does not mean "look for packages with + ls in the root directory," since the + / can match anywhere in the path. It's just there to + anchor the match so that it matches a full filename. + + By default the matching is case-sensitive. To get a case insensitive + match, begin your regexp with (?i) which is a + PCRE-specific feature. For complete documentation on Perl-compatible + regular expression syntax and options, read the perlre + manpage, or one of many websites such as perldoc.com + that document the Perl language. + + The cygcheck program should be used to send + information about your system for troubleshooting when requested. When + asked to run this command save the output so that you can email it, for + example: + + +$ cygcheck -s -v -r -h > cygcheck_output.txt + + + Each Cygwin DLL stores its path and installation key in the + registry. This allows troubleshooting of problems which could be a result + of having multiple concurrent Cygwin installations. However, if you're + experimenting a lot with different Cygwin installation paths, your + registry could accumulate a lot of old Cygwin installation entries for + which the installation doesn't exist anymore. To get rid of these + orphaned registry entries, use the cygcheck + --delete-orphaned-installation-keys command. + + Each Cygwin DLL generates a key value from its installation path. + This value is not only stored in the registry, it's also used to generate + global object names used for interprocess communication. This keeps + different Cygwin installations separate. Processes running under a Cygwin + DLL installed in C:\cygwin don't see processes running under a Cygwin DLL + installed in C:\Program Files\cygwin. This allows running multiple + versions of Cygwin DLLs without these versions to interfere with each + other, or to run small third-party installations for a specific purpose + independently from a Cygwin net distribution. + + For debugging purposes it could be desired that the various Cygwin + DLLs use the same key, independently from their installation paths. If + the DLLs have different versions, trying to run processes under these + DLLs concurrently will result in error messages like this one: + + +*** shared version mismatch detected - 0x8A88009C/0x75BE0074. +This problem is probably due to using incompatible versions of the Cygwin DLL. +Search for cygwin1.dll using the Windows Start->Find/Search facility +and delete all but the most recent version. The most recent version *should* +reside in x:\\cygwin\\bin, where 'x' is the drive on which you have +installed the cygwin distribution. Rebooting is also suggested if you +are unable to find another Cygwin DLL. + + + To disable the usage of a unique key value of a certain Cygwin DLL, + use the cygcheck --disable-unique-object-names + Cygwin-DLL command. Cygwin-DLL is the + Windows path (*not* a Cygwin POSIX path) to the DLL for which you want to + disable this feature. Note that you have to stop all Cygwin processes + running under this DLL, before you're allowed to change this setting. For + instance, run cygcheck from a DOS command line for + this purpose. + + To re-enable the usage of a unique key, use the cygcheck + --enable-unique-object-names Cygwin-DLL command. This option + has the same characteristics as the + --disable-unique-object-names option + + Finally, you can use cygcheck --show-unique-object-names + Cygwin-DLL to find out if the given Cygwin DLL use unique + object names or not. In contrast to the --disable-... + and --enable-... options, the + --show-unique-object-names option also works for + Cygwin DLLs which are currently in use. + + + + + cygpath + + +Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME... + cygpath [-c HANDLE] + cygpath [-ADHOPSW] + cygpath [-F ID] + +Convert Unix and Windows format paths, or output system path information + +Output type options: + + -d, --dos print DOS (short) form of NAMEs (C:\PROGRA~1\) + -m, --mixed like --windows, but with regular slashes (C:/WINNT) + -M, --mode report on mode of file (currently binmode or textmode) + -u, --unix (default) print Unix form of NAMEs (/cygdrive/c/winnt) + -w, --windows print Windows form of NAMEs (C:\WINNT) + -t, --type TYPE print TYPE form: 'dos', 'mixed', 'unix', or 'windows' + +Path conversion options: + + -a, --absolute output absolute path + -l, --long-name print Windows long form of NAMEs (with -w, -m only) + -p, --path NAME is a PATH list (i.e., '/bin:/usr/bin') + -s, --short-name print DOS (short) form of NAMEs (with -w, -m only) + -C, --codepage CP print DOS, Windows, or mixed pathname in Windows + codepage CP. CP can be a numeric codepage identifier, + or one of the reserved words ANSI, OEM, or UTF8. + If this option is missing, cygpath defaults to the + character set defined by the current locale. + +System information: + + -A, --allusers use `All Users' instead of current user for -D, -P + -D, --desktop output `Desktop' directory and exit + -H, --homeroot output `Profiles' directory (home root) and exit + -O, --mydocs output `My Documents' directory and exit + -P, --smprograms output Start Menu `Programs' directory and exit + -S, --sysdir output system directory and exit + -W, --windir output `Windows' directory and exit + -F, --folder ID output special folder with numeric ID and exit + +Other options: + + -f, --file FILE read FILE for input; use - to read from STDIN + -o, --option read options from FILE as well (for use with --file) + -c, --close HANDLE close HANDLE (for use in captured process) + -i, --ignore ignore missing argument + -h, --help output usage information and exit + -V, --version output version information and exit + + + The cygpath program is a utility that converts + Windows native filenames to Cygwin POSIX-style pathnames and vice versa. + It can be used when a Cygwin program needs to pass a file name to a + native Windows program, or expects to get a file name from a native + Windows program. Alternatively, cygpath can output + information about the location of important system directories in either + format. + + The -u and -w options indicate + whether you want a conversion to UNIX (POSIX) format + (-u) or to Windows format (-w). Use + the -d to get DOS-style (8.3) file and path names. The + -m option will output Windows-style format but with + forward slashes instead of backslashes. This option is especially useful + in shell scripts, which use backslashes as an escape character. + + In combination with the -w option, you can use + the -l and -s options to use normal + (long) or DOS-style (short) form. The -d option is + identical to -w and -s together. + + The -C option allows to specify a Windows codepage + to print DOS and Windows paths created with one of the + -d, -m, or -w + options. The default is to use the character set of the current locale + defined by one of the internationalization environment variables + LC_ALL, LC_CTYPE, or LANG, + see . This is sometimes not sufficient for + interaction with native Windows tools, which might expect native, + non-ASCII characters in a specific Windows codepage. Console tools, for + instance, might expect pathnames in the current OEM codepage, while + graphical tools like Windows Explorer might expect pathnames in the + current ANSI codepage. + + The -C option takes a single parameter: + + + ANSI, to specify the current ANSI + codepage + + + OEM, to specify the current OEM (console) + codepage + + + UTF8, to specify UTF-8. + + + A numerical, decimal codepage number, for instance 936 for GBK, + 28593 for ISO-8859-3, etc. A full list of supported codepages is + listed on the Microsoft MSDN page Code Page Identifiers. A codepage of 0 is the same as if the + -C hasn't been specified at all. + + + + The -p option means that you want to convert a + path-style string rather than a single filename. For example, the PATH + environment variable is semicolon-delimited in Windows, but + colon-delimited in UNIX. By giving -p you are + instructing cygpath to convert between these + formats. + + The -i option supresses the print out of the usage + message if no filename argument was given. It can be used in make file + rules converting variables that may be omitted to a proper format. Note + that cygpath output may contain spaces (C:\Program + Files) so should be enclosed in quotes. + + + + Example <command>cygpath</command> usage + + + + + + The capital options -D, -H, + -P, -S, and -W + output directories used by Windows that are not the same on all systems, + for example -S might output C:\WINNT\system32 or + C:\Windows\System32. The -H shows the Windows profiles + directory that can be used as root of home. The -A + option forces use of the "All Users" directories instead of the current + user for the -D, -O and + -P options. The -F outputs other + special folders specified by their internal numeric code (decimal or + 0x-prefixed hex). For valid codes and symbolic names, see the CSIDL_* + definitions in the include file /usr/include/w32api/shlobj.h from package + w32api. The current valid range of codes for folders is 0 (Desktop) to 59 + (CDBurn area). By default the output is in UNIX (POSIX) format; use the + -w or -d options to get other + formats. + + + + + dumper + + +Usage: dumper [OPTION] FILENAME WIN32PID + +Dump core from WIN32PID to FILENAME.core + +-d, --verbose be verbose while dumping +-h, --help output help information and exit +-q, --quiet be quiet while dumping (default) +-V, --version output version information and exit + + + The dumper utility can be used to create a core + dump of running Windows process. This core dump can be later loaded to + gdb and analyzed. One common way to use + dumper is to plug it into cygwin's Just-In-Time + debugging facility by adding + +error_start=x:\path\to\dumper.exe + to the + CYGWIN environment variable. Please note that + x:\path\to\dumper.exe is Windows-style and not cygwin + path. If error_start is set this way, then dumper will + be started whenever some program encounters a fatal error. + + dumper can be also be started from the command + line to create a core dump of any running process. Unfortunately, because + of a Windows API limitation, when a core dump is created and + dumper exits, the target process is terminated too. + + To save space in the core dump, dumper doesn't + write those portions of target process' memory space that are loaded from + executable and dll files and are unchangeable, such as program code and + debug info. Instead, dumper saves paths to files which + contain that data. When a core dump is loaded into gdb, it uses these + paths to load appropriate files. That means that if you create a core + dump on one machine and try to debug it on another, you'll need to place + identical copies of the executable and dlls in the same directories as on + the machine where the core dump was created. + + + + + getconf + + +Usage: getconf [-v specification] variable_name [pathname] + getconf -a [pathname] + +Get configuration values + + -v specification Indicate specific version for which configuration + values shall be fetched. + -a, --all Print all known configuration values + +Other options: + + -h, --help This text + -V, --version Print program version and exit + + + The getconf utility prints the value of the + configuration variable specified by variable_name. If + no pathname is given, getconf + serves as a wrapper for the confstr and + sysconf functions, supporting the symbolic constants + defined in the limits.h and + unistd.h headers, without their respective + _CS_ or _SC_ prefixes. + + If pathname is given, getconf + prints the value of the configuration variable for the specified + pathname. In this form, getconf serves as a wrapper + for the pathconf function, supporting the symbolic + constants defined in the unistd.h header, without the + _PC_ prefix. + + If you specify the -v option, the parameter + denotes a specification for which the value of the configuration variable + should be printed. Note that the only specifications supported by Cygwin + are POSIX_V7_ILP32_OFFBIG and the legacy + POSIX_V6_ILP32_OFFBIG and + XBS5_ILP32_OFFBIG equivalents. + + Use the -a option to print a list of all available + configuration variables for the system, or given + pathname, and their values. + + + + + getfacl + + +Usage: getfacl [-adn] FILE [FILE2...] + +Display file and directory access control lists (ACLs). + + -a, --all display the filename, the owner, the group, and + the ACL of the file + -d, --dir display the filename, the owner, the group, and + the default ACL of the directory, if it exists + -h, --help output usage information and exit + -n, --noname display user and group IDs instead of names + -V, --version output version information and exit + +When multiple files are specified on the command line, a blank +line separates the ACLs for each file. + + + For each argument that is a regular file, special file or directory, + getfacl displays the owner, the group, and the ACL. + For directories getfacl displays additionally the + default ACL. With no options specified, getfacl + displays the filename, the owner, the group, and both the ACL and the + default ACL, if it exists. For more information on Cygwin and Windows + ACLs, see in the Cygwin User's Guide. The format + for ACL output is as follows: + + # file: filename + # owner: name or uid + # group: name or uid + user::perm + user:name or uid:perm + group::perm + group:name or gid:perm + mask:perm + other:perm + default:user::perm + default:user:name or uid:perm + default:group::perm + default:group:name or gid:perm + default:mask:perm + default:other:perm + + + + + + kill + + +Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...] + kill -l [signal] + +Send signals to processes + + -f, --force force, using win32 interface if necessary + -l, --list print a list of signal names + -s, --signal send signal (use kill --list for a list) + -h, --help output usage information and exit + -V, --version output version information and exit + + + The kill program allows you to send arbitrary + signals to other Cygwin programs. The usual purpose is to end a running + program from some other window when ^C won't work, but you can also send + program-specified signals such as SIGUSR1 to trigger actions within the + program, like enabling debugging or re-opening log files. Each program + defines the signals they understand. + + You may need to specify the full path to use kill + from within some shells, including bash, the default + Cygwin shell. This is because bash defines a + kill builtin function; see the bash + man page under BUILTIN COMMANDS for more + information. To make sure you are using the Cygwin version, try + +$ /bin/kill --version + which should give the Cygwin + kill version number and copyright information. + + Unless you specific the -f option, the "pid" + values used by kill are the Cygwin pids, not the + Windows pids. To get a list of running programs and their Cygwin pids, + use the Cygwin ps program. ps -W + will display all windows pids. + + The kill -l option prints the name of the given + signal, or a list of all signal names if no signal is given. + + To send a specific signal, use the -signN option, + either with a signal number or a signal name (minus the "SIG" part), as + shown in these examples: + + + Using the kill command + +$ kill 123 +$ kill -1 123 +$ kill -HUP 123 +$ kill -f 123 + + + + Here is a list of available signals, their numbers, and some + commentary on them, from the file + <sys/signal.h>, which should be considered the + official source of this information. + + +SIGHUP 1 hangup +SIGINT 2 interrupt +SIGQUIT 3 quit +SIGILL 4 illegal instruction (not reset when caught) +SIGTRAP 5 trace trap (not reset when caught) +SIGABRT 6 used by abort +SIGEMT 7 EMT instruction +SIGFPE 8 floating point exception +SIGKILL 9 kill (cannot be caught or ignored) +SIGBUS 10 bus error +SIGSEGV 11 segmentation violation +SIGSYS 12 bad argument to system call +SIGPIPE 13 write on a pipe with no one to read it +SIGALRM 14 alarm clock +SIGTERM 15 software termination signal from kill +SIGURG 16 urgent condition on IO channel +SIGSTOP 17 sendable stop signal not from tty +SIGTSTP 18 stop signal from tty +SIGCONT 19 continue a stopped process +SIGCHLD 20 to parent on child stop or exit +SIGCLD 20 System V name for SIGCHLD +SIGTTIN 21 to readers pgrp upon background tty read +SIGTTOU 22 like TTIN for output if (tp->t_local&LTOSTOP) +SIGIO 23 input/output possible +SIGPOLL 23 System V name for SIGIO +SIGXCPU 24 exceeded CPU time limit +SIGXFSZ 25 exceeded file size limit +SIGVTALRM 26 virtual time alarm +SIGPROF 27 profiling time alarm +SIGWINCH 28 window changed +SIGLOST 29 resource lost (eg, record-lock lost) +SIGPWR 29 power failure +SIGUSR1 30 user defined signal 1 +SIGUSR2 31 user defined signal 2 + + + + + + ldd + + +Usage: ldd [OPTION]... FILE... + +Print shared library dependencies + + -h, --help print this help and exit + -V, --version print version information and exit + -r, --function-relocs process data and function relocations + (currently unimplemented) + -u, --unused print unused direct dependencies + (currently unimplemented) + -v, --verbose print all information + (currently unimplemented) + + + ldd prints the shared libraries (DLLs) an + executable or DLL is linked against. No modifying option is implemented + yet. + + + + + locale + + +Usage: locale [-amvhV] + or: locale [-ck] NAME + or: locale [-usfnU] + +Get locale-specific information. + +System information: + + -a, --all-locales List all available supported locales + -m, --charmaps List all available character maps + -v, --verbose More verbose output + +Modify output format: + + -c, --category-name List information about given category NAME + -k, --keyword-name Print information about given keyword NAME + +Default locale information: + + -u, --user Print locale of user's default UI language + -s, --system Print locale of system default UI language + -f, --format Print locale of user's regional format settings + (time, numeric & monetary) + -n, --no-unicode Print system default locale for non-Unicode programs + -U, --utf Attach \".UTF-8\" to the result + +Other options: + + -h, --help This text + -V, --version Print program version and exit + + + locale without parameters prints information about + the current locale environment settings. + + The -u, -s, + -f, and -n options can be used to + request the various Windows locale settings. The purpose is to use this + command in scripts to set the POSIX locale variables. + + The -u option prints the current user's Windows UI + locale to stdout. In Windows Vista and Windows 7 this setting is called + the "Display Language"; there was no corresponding user setting in + Windows XP. The -s option prints the systems default + instead. The -f option prints the user's setting for + time, date, number and currency. That's equivalent to the setting in the + "Formats" or "Regional Options" tab in the "Region and Language" or + "Regional and Language Options" dialog. With the -U + option locale appends a ".UTF-8". + + Usage example: + + +bash$ export LANG=$(locale -uU) +bash$ echo $LANG +en_US.UTF-8 +bash$ export LC_TIME=$(locale -fU) +bash$ echo $LC_TIME +de_DE.UTF-8 + + + The -a option is helpful to learn which locales + are supported by your Windows machine. It prints all available locales + and the allowed modifiers. Example: + + +bash$ locale -a +C +C.utf8 +POSIX +af_ZA +af_ZA.utf8 +am_ET +am_ET.utf8 +... +be_BY +be_BY.utf8 +be_BY@latin +... +ca_ES +ca_ES.utf8 +ca_ES@euro +catalan +... + + + The -v option prints more detailed information + about each available locale. Example: + + +bash$ locale -av +locale: af_ZA archive: /cygdrive/c/Windows/system32/kernel32.dll +------------------------------------------------------------------------------- + language | Afrikaans +territory | South Africa + codeset | ISO-8859-1 + +locale: af_ZA.utf8 archive: /cygdrive/c/Windows/system32/kernel32.dll +------------------------------------------------------------------------------- + language | Afrikaans +territory | South Africa + codeset | UTF-8 + +... + +locale: ca_ES@euro archive: /cygdrive/c/Windows/system32/kernel32.dll +------------------------------------------------------------------------------- + language | Catalan +territory | Spain + codeset | ISO-8859-15 + +locale: catalan archive: /usr/share/locale/locale.alias +------------------------------------------------------------------------------- + language | Catalan +territory | Spain + codeset | ISO-8859-1 + +... + + + The -m option prints the names of the available + charmaps supported by Cygwin to stdout. + + Otherwise, if arguments are given, locale prints + the values assigned to these arguments. Arguments can be names of locale + categories (for instance: LC_CTYPE, LC_MONETARY), or names of keywords + supported in the locale categories (for instance: thousands_sep, + charmap). The -c option prints additionally the name + of the category. The -k option prints additionally the + name of the keyword. Example: + + +bash$ locale -ck LC_MESSAGES +LC_MESSAGES +yesexpr="^[yY]" +noexpr="^[nN]" +yesstr="yes" +nostr="no" +messages-codeset="UTF-8" +bash$ locale noexpr +^[nN] + + + + + minidumper + + +Usage: minidumper [OPTION] FILENAME WIN32PID + +Write minidump from WIN32PID to FILENAME.dmp + +-t, --type minidump type flags +-n, --nokill don't terminate the dumped process +-d, --verbose be verbose while dumping +-h, --help output help information and exit +-q, --quiet be quiet while dumping (default) +-V, --version output version information and exit + + + + The minidumper utility can be used to create a + minidump of a running Windows process. This minidump can be later + analysed using breakpad or Windows debugging tools. + + + + minidumper can be used with cygwin's Just-In-Time + debugging facility in exactly the same way as dumper + (See ). + + + + minidumper can also be started from the command line to + create a minidump of any running process. For compatibility with + dumper the target process is terminated after dumping + unless the -n option is given. + + + + + + mkgroup + + +Usage: mkgroup [OPTION]... + +Write /etc/group-like output to stdout + +Don't use this command to generate a local /etc/group file, unless you +really need one. See the Cygwin User's Guide for more information. + +Options: + + -l,--local [machine] print local groups + (from local machine if no machine specified) + -L,--Local machine ditto, but generate groupname with machine prefix + -d,--domain [domain] print domain groups + (from current domain if no domain specified) + -c,--current print current group + -S,--separator char for -l use character char as domain\group + separator in groupname instead of default '+' + -o,--id-offset offset change the default offset (0x10000) added to + gids of foreign machine accounts. + -g,--group groupname only return information for the specified group + one of -l, -d must be specified, too + -b,--no-builtin don't print BUILTIN groups + -U,--unix grouplist print UNIX groups when using -l on a UNIX Samba + server. grouplist is a comma-separated list of + groupnames or gid ranges (root,-25,50-100). + (enumerating large ranges can take a long time!) + -h,--help print this message + -v,--version print version information and exit + +Default is to print local groups on stand-alone machines, plus domain +groups on domain controllers and domain member machines. + + + The mkgroup program can be used to create a local + /etc/group file. Cygwin doesn't need this file, + because it reads group information from the Windows account databases, + but you can add an /etc/group file for instance, if + your machine is often disconnected from its domain controller. + + + Note that this information is static, in contrast to the information + automatically gathered by Cygwin from the Windows account databases. If + you change the group information on your system, you'll need to regenerate + the group file for it to have the new information. + + By default, the information generated by mkgroup + is equivalent to the information generated by Cygwin itself. The + -d and -l/-L options allow you to + specify where the information comes from, some domain, or the local SAM + of a machine. Note that you can only enumerate accounts from trusted + domains. Any non-trusted domain will be ignored. Access-restrictions + of your current account apply. The -l/-L when used + with a machine name, tries to contact that machine to enumerate local + groups of other machines, typically outside of domains. This scenario + cannot be covered by Cygwin's account automatism. If you want to use + the -L option, but you don't like the default + domain/group separator from /etc/nsswitch.conf, + you can specify another separator using the -S option, + for instance: + + + Setting up group entry for current user with different + domain/group separator + +$ mkgroup -L server1 -S= > /etc/group + + + + For very simple needs, an entry for the current user's group can be + created by using the option -c. + + The -o option allows for (unlikely) special cases + with multiple machines where the GIDs might match otherwise. The + -g option only prints the information for one group. + The -U option allows you to enumerate the standard + UNIX groups on a Samba machine. It's used together with -l + samba-server or -L samba-server. The normal + UNIX groups are usually not enumerated, but they can show up as a group + in ls -l output. + + + + + mkpasswd + + +Usage: mkpasswd [OPTIONS]... + +Write /etc/passwd-like output to stdout + +Don't use this command to generate a local /etc/passwd file, unless you +really need one. See the Cygwin User's Guide for more information. + +Options: + + -l,--local [machine] print local user accounts + (from local machine if no machine specified) + -L,--Local machine ditto, but generate username with machine prefix + -d,--domain [domain] print domain accounts + (from current domain if no domain specified) + -c,--current print current user + -S,--separator char for -l use character char as domain\user + separator in username instead of the default '+' + -o,--id-offset offset change the default offset (0x10000) added to uids + in domain or foreign server accounts. + -u,--username username only return information for the specified user + one of -l, -d must be specified, too + -b,--no-builtin don't print BUILTIN users + -p,--path-to-home path use specified path instead of user account home dir + or /home prefix + -U,--unix userlist print UNIX users when using -l on a UNIX Samba + server. userlist is a comma-separated list of + usernames or uid ranges (root,-25,50-100). + (enumerating large ranges can take a long time!) + -h,--help displays this message + -V,--version version information and exit + +Default is to print local accounts on stand-alone machines, domain accounts +on domain controllers and domain member machines. + + + The mkpasswd program can be used to create a + /etc/passwd file. Cygwin doesn't need this file, + because it reads user information from the Windows account databases, + but you can add an /etc/group file for instance, if + your machine is often disconnected from its domain controller. + + Note that this information is static, in contrast to the information + automatically gathered by Cygwin from the Windows account databases. If + you change the user information on your system, you'll need to regenerate + the passwd file for it to have the new information. + + By default, the information generated by mkpasswd + is equivalent to the information generated by Cygwin itself. The + -d and -l/-L options allow you to + specify where the information comes from, some domain, or the local SAM + of a machine. Note that you can only enumerate accounts from trusted + domains. Any non-trusted domain will be ignored. Access-restrictions + of your current account apply. The -l/-L when used + with a machine name, tries to contact that machine to enumerate local + groups of other machines, typically outside of domains. This scenario + cannot be covered by Cygwin's account automatism. If you want to use + the -L option, but you don't like the default + domain/group separator from /etc/nsswitch.conf, + you can specify another separator using the -S option, + analog to mkgroup. + + For very simple needs, an entry for the current user can be created + by using the option -c. + + The -o option allows for special cases (such as + multiple domains) where the UIDs might match otherwise. The + -p option causes mkpasswd to use + the specified prefix instead of the account home dir or /home/ + . For example, this command: Using an alternate home root + +$ mkpasswd -l -p "$(cygpath -H)" > /etc/passwd + + would put local users' home directories in the Windows + 'Profiles' directory. The -u option creates just an + entry for the specified user. The -U option allows you + to enumerate the standard UNIX users on a Samba machine. It's used + together with -l samba-server or -L + samba-server. The normal UNIX users are usually not enumerated, + but they can show up as file owners in ls -l output. + + + + + + mount + + +Usage: mount [OPTION] [<win32path> <posixpath>] + mount -a + mount <posixpath> + +Display information about mounted filesystems, or mount a filesystem + + -a, --all mount all filesystems mentioned in fstab + -c, --change-cygdrive-prefix change the cygdrive path prefix to <posixpath> + -f, --force force mount, don't warn about missing mount + point directories + -h, --help output usage information and exit + -m, --mount-entries write fstab entries to replicate mount points + and cygdrive prefixes + -o, --options X[,X...] specify mount options + -p, --show-cygdrive-prefix show user and/or system cygdrive path prefix + -V, --version output version information and exit + + + The mount program is used to map your drives and + shares onto Cygwin's simulated POSIX directory tree, much like as is done + by mount commands on typical UNIX systems. However, in contrast to mount + points given in /etc/fstab, mount points created or + changed with mount are not persistent. They disappear + immediately after the last process of the current user exited. Please see + for more information on the concepts behind + the Cygwin POSIX file system and strategies for using mounts. To remove + mounts temporarily, use umount + + + Using mount + + If you just type mount with no parameters, it + will display the current mount table for you. + + + Displaying the current set of mount points + +$ mount +C:/cygwin/bin on /usr/bin type ntfs (binary) +C:/cygwin/lib on /usr/lib type ntfs (binary) +C:/cygwin on / type ntfs (binary) +C: on /mnt/c type ntfs (binary,user,noumount) +D: on /mnt/d type fat (binary,user,noumount) + + + + In this example, c:/cygwin is the POSIX root and the D drive is + mapped to /mnt/d. Note that in this case, the root + mount is a system-wide mount point that is visible to all users running + Cygwin programs, whereas the /mnt/d mount is only + visible to the current user. + + The mount utility is also the mechanism for + adding new mounts to the mount table in memory. The following example + demonstrates how to mount the directory + //pollux/home/joe/data to + /data for the duration of the current session. + + + Adding mount points + +$ ls /data +ls: /data: No such file or directory +$ mount //pollux/home/joe/data /data +mount: warning - /data does not exist! +$ mount +//pollux/home/joe/data on /data type smbfs (binary) +C:/cygwin/bin on /usr/bin type ntfs (binary) +C:/cygwin/lib on /usr/lib type ntfs (binary) +C:/cygwin on / type ntfs (binary) +C: on /c type ntfs (binary,user,noumount) +D: on /d type fat (binary,user,noumount) + + + + A given POSIX path may only exist once in the mount table. Attempts + to replace the mount will fail with a busy error. The + -f (force) option causes the old mount to be + silently replaced with the new one, provided the old mount point was a + user mount point. It's not valid to replace system-wide mount points. + Additionally, the -f option will silence warnings + about the non-existence of directories at the Win32 path + location. + + The -o option is the method via which various + options about the mount point may be recorded. The following options + are available (note that most of the options are duplicates of other + mount flags): + + + acl - Use the filesystem's access control lists (ACLs) to + implement real POSIX permissions (default). + binary - Files default to binary mode (default). + bind - Allows to remount part of the file hierarchy somewhere else. + Different from other mount calls, the first argument + specifies an absolute POSIX path, rather than a Win32 path. + This POSIX path is remounted to the POSIX path specified as + the second parameter. The conversion to a Win32 path is done + within Cygwin immediately at the time of the call. Note that + symlinks are ignored while performing this path conversion. + cygexec - Treat all files below mount point as cygwin executables. + dos - Always convert leading spaces and trailing dots and spaces to + characters in the UNICODE private use area. This allows to use + broken filesystems which only allow DOS filenames, even if they + are not recognized as such by Cygwin. + exec - Treat all files below mount point as executable. + ihash - Always fake inode numbers rather than using the ones returned + by the filesystem. This allows to use broken filesystems which + don't return unambiguous inode numbers, even if they are not + recognized as such by Cygwin. + noacl - Ignore ACLs and fake POSIX permissions. + nosuid - No suid files are allowed (currently unimplemented) + notexec - Treat all files below mount point as not executable. + override - Override immutable mount points. + posix=0 - Switch off case sensitivity for paths under this mount point. + posix=1 - Switch on case sensitivity for paths under this mount point + (default). + sparse - Switch on support for sparse files. This option only makes + sense on NTFS and then only if you really need sparse files. + text - Files default to CRLF text mode line endings. + + + For a more complete description of the mount options and the + /etc/fstab file, see . + + Note that all mount points added with mount are + user mount points. System mount points can only be specified in the + /etc/fstab file. + + If you added mount points to /etc/fstab or + your /etc/fstab.d/<username> file, you can + add these mount points to your current user session using the + -a/--all option, or by specifing the posix path + alone on the command line. As an example, consider you added a mount + point with the POSIX path /my/mount. You can add + this mount point with either one of the following two commands to your + current user session. + + +$ mount /my/mount +$ mount -a + + + The first command just adds the /my/mount + mount point to your current session, the mount -a + adds all new mount points to your user session. + + If you change a mount point to point to another native path, or if + you changed the flags of a mount point, you have to + umount the mount point first, before you can add it + again. Please note that all such added mount points are added as user + mount points, and that the rule that system mount points can't be + removed or replaced in a running session still applies. + + To bind a POSIX path to another POSIX path, use the + bind mount flag. + + +$ mount -o bind /var /usr/var + + + This command makes the file hirarchy under + /var additionally available under + /usr/var. + + The -m option causes the + mount utility to output the current mount table in a + series of fstab entries. You can save this output as a backup when + experimenting with the mount table. Copy the output to + /etc/fstab to restore the old state. It also makes + moving your settings to a different machine much easier. + + + + + Cygdrive mount points + + Whenever Cygwin cannot use any of the existing mounts to convert + from a particular Win32 path to a POSIX one, Cygwin will, instead, + convert to a POSIX path using a default mount point: + /cygdrive. For example, if Cygwin accesses + z:\foo and the z drive is not currently in the + mount table, then z:\ will be accessible as + /cygdrive/z. The mount utility + can be used to change this default automount prefix through the use of + the "--change-cygdrive-prefix" option. In the following example, we + will set the automount prefix to /mnt: + + + Changing the default prefix + +$ mount --change-cygdrive-prefix /mnt + + + + Note that the cygdrive prefix can be set both per-user and + system-wide, and that as with all mounts, a user-specific mount takes + precedence over the system-wide setting. The mount + utility creates system-wide mounts by default if you do not specify a + type. You can always see the user and system cygdrive prefixes with the + -p option. Using the --options + flag with --change-cygdrive-prefix makes all new + automounted filesystems default to this set of options. For instance + (using the short form of the command line flags) + + + Changing the default prefix with specific mount options + +$ mount -c /mnt -o binary,noacl + + + + + + + + Limitations + + Limitations: there is a hard-coded limit of 64 mount points (up to + Cygwin 1.7.9: 30 mount points). Also, although you can mount to + pathnames that do not start with "/", there is no way to make use of + such mount points. + + Normally the POSIX mount point in Cygwin is an existing empty + directory, as in standard UNIX. If this is the case, or if there is a + place-holder for the mount point (such as a file, a symbolic link + pointing anywhere, or a non-empty directory), you will get the expected + behavior. Files present in a mount point directory before the mount + become invisible to Cygwin programs. + + It is sometimes desirable to mount to a non-existent directory, for + example to avoid cluttering the root directory with names such as + a, b, c + pointing to disks. Although mount will give you a + warning, most everything will work properly when you refer to the mount + point explicitly. Some strange effects can occur however. For example + if your current working directory is /dir, say, + and /dir/mtpt is a mount point, then + mtpt will not show up in an ls + or echo * command and find . will + not find mtpt. + + + + + + + passwd + + +Usage: passwd [OPTION] [USER] + +Change USER's password or password attributes. + +User operations: + -l, --lock lock USER's account. + -u, --unlock unlock USER's account. + -c, --cannot-change USER can't change password. + -C, --can-change USER can change password. + -e, --never-expires USER's password never expires. + -E, --expires USER's password expires according to system's + password aging rule. + -p, --pwd-not-required no password required for USER. + -P, --pwd-required password is required for USER. + -R, --reg-store-pwd enter password to store it in the registry for + later usage by services to be able to switch + to this user context with network credentials. + +System operations: + -i, --inactive NUM set NUM of days before inactive accounts are disabled + (inactive accounts are those with expired passwords). + -n, --minage MINDAYS set system minimum password age to MINDAYS days. + -x, --maxage MAXDAYS set system maximum password age to MAXDAYS days. + -L, --length LEN set system minimum password length to LEN. + +Other options: + -d, --logonserver SERVER connect to SERVER (e.g. domain controller). + Default server is the local system, unless + changing the current user, in which case the + default is the content of $LOGONSERVER. + -S, --status display password status for USER (locked, expired, + etc.) plus global system password settings. + -h, --help output usage information and exit. + -V, --version output version information and exit. + +If no option is given, change USER's password. If no user name is given, +operate on current user. System operations must not be mixed with user +operations. Don't specify a USER when triggering a system operation. + +Don't specify a user or any other option together with the -R option. +Non-Admin users can only store their password if cygserver is running. +Note that storing even obfuscated passwords in the registry is not overly +secure. Use this feature only if the machine is adequately locked down. +Don't use this feature if you don't need network access within a remote +session. You can delete your stored password by using `passwd -R' and +specifying an empty password. + + + passwd changes passwords for user accounts. A + normal user may only change the password for their own account, but + administrators may change passwords on any account. + passwd also changes account information, such as + password expiry dates and intervals. + + For password changes, the user is first prompted for their old + password, if one is present. This password is then encrypted and compared + against the stored password. The user has only one chance to enter the + correct password. The administrators are permitted to bypass this step so + that forgotten passwords may be changed. + + The user is then prompted for a replacement password. + passwd will prompt twice for this replacement and + compare the second entry against the first. Both entries are required to + match in order for the password to be changed. + + After the password has been entered, password aging information is + checked to see if the user is permitted to change their password at this + time. If not, passwd refuses to change the password + and exits. + + To get current password status information, use the + -S option. Administrators can use + passwd to perform several account maintenance + functions (users may perform some of these functions on their own + accounts). Accounts may be locked with the -l flag and + unlocked with the -u flag. Similarly, + -c disables a user's ability to change passwords, and + -C allows a user to change passwords. For password + expiry, the -e option disables expiration, while the + -E option causes the password to expire according to + the system's normal aging rules. Use -p to disable the + password requirement for a user, or -P to require a + password. + + Administrators can also use passwd to change + system-wide password expiry and length requirements with the + -i, -n, -x, and + -L options. The -i option is used + to disable an account after the password has been expired for a number of + days. After a user account has had an expired password for + NUM days, the user may no longer sign on to the + account. The -n option is used to set the minimum + number of days before a password may be changed. The user will not be + permitted to change the password until MINDAYS days + have elapsed. The -x option is used to set the maximum + number of days a password remains valid. After + MAXDAYS days, the password is required to be + changed. Allowed values for the above options are 0 to 999. The + -L option sets the minimum length of allowed passwords + for users who don't belong to the administrators group to + LEN characters. Allowed values for the minimum + password length are 0 to 14. In any of the above cases, a value of 0 + means `no restrictions'. + + All operations affecting the current user are by default run against + the logon server of the current user (taken from the environment variable + LOGONSERVER. When password or account information of other + users should be changed, the default server is the local system. To + change a user account on a remote machine, use the -d + option to specify the machine to run the command against. Note that the + current user must be a valid member of the administrators group on the + remote machine to perform such actions. + + Users can use the passwd -R to enter a password + which then gets stored in a special area of the registry on the local + system, which is also used by Windows to store passwords of accounts + running Windows services. When a privileged Cygwin application calls the + set{e}uid(user_id) system call, Cygwin checks if a + password for that user has been stored in this registry area. If so, it + uses this password to switch to this user account using that password. + This allows you to logon through, for instance, ssh + with public key authentication and get a full qualified user token with + all credentials for network access. However, the method has some + drawbacks security-wise. This is explained in more detail in . + + Please note that storing passwords in that registry area is a + privileged operation which only administrative accounts are allowed to + do. Administrators can enter the password for other user accounts into + the registry by specifying the username on the commandline. If normal, + non-admin users should be allowed to enter their passwords using + passwd -R, it's required to run + cygserver as a service under the LocalSystem account + before running passwd -R. This only affects storing + passwords. Using passwords in privileged processes does not require + cygserver to run. + + Limitations: Users may not be able to change their password on some + systems. + + + + + pldd + + +Usage: pldd [OPTION...] PID + +List dynamic shared objects loaded into a process. + + -?, --help Give this help list + --usage Give a short usage message + -V, --version Print program version + + + pldd prints the shared libraries (DLLs) loaded by + the process with the given PID. + + + + + ps + + +Usage: ps [-aefls] [-u UID] + +Report process status + + -a, --all show processes of all users + -e, --everyone show processes of all users + -f, --full show process uids, ppids + -h, --help output usage information and exit + -l, --long show process uids, ppids, pgids, winpids + -p, --process show information for specified PID + -s, --summary show process summary + -u, --user list processes owned by UID + -V, --version output version information and exit + -W, --windows show windows as well as cygwin processes +With no options, ps outputs the long format by default + + + The ps program gives the status of all the Cygwin + processes running on the system (ps = "process status"). Due to the + limitations of simulating a POSIX environment under Windows, there is + little information to give. + + The PID column is the process ID you need to give to the + kill command. The PPID is the parent process ID, and + PGID is the process group ID. The WINPID column is the process ID + displayed by NT's Task Manager program. The TTY column gives which + pseudo-terminal a process is running on, or a '?' for + services. The UID column shows which user owns each process. STIME is the + time the process was started, and COMMAND gives the name of the program + running. Listings may also have a status flag in column zero; + S means stopped or suspended (in other words, in the + background), I means waiting for input or interactive + (foreground), and O means waiting to output. + + By default, ps will only show processes owned by + the current user. With either the -a or + -e option, all user's processes (and system processes) + are listed. There are historical UNIX reasons for the synonomous options, + which are functionally identical. The -f option + outputs a "full" listing with usernames for UIDs. The + -l option is the default display mode, showing a + "long" listing with all the above columns. The other display option is + -s, which outputs a shorter listing of just PID, TTY, + STIME, and COMMAND. The -u option allows you to show + only processes owned by a specific user. The -p option + allows you to show information for only the process with the specified + PID. The -W option causes ps show + non-Cygwin Windows processes as well as Cygwin processes. The WINPID is + also the PID, and they can be killed with the Cygwin + kill command's -f option. + + + + + regtool + + +Usage: regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY + +View or edit the Win32 registry + +Actions: + + add KEY\SUBKEY add new SUBKEY + check KEY exit 0 if KEY exists, 1 if not + get KEY\VALUE prints VALUE to stdout + list KEY list SUBKEYs and VALUEs + remove KEY remove KEY + set KEY\VALUE [data ...] set VALUE + unset KEY\VALUE removes VALUE from KEY + load KEY\SUBKEY PATH load hive from PATH into new SUBKEY + unload KEY\SUBKEY unload hive and remove SUBKEY + save KEY\SUBKEY PATH save SUBKEY into new hive PATH + +Options for 'list' Action: + + -k, --keys print only KEYs + -l, --list print only VALUEs + -p, --postfix like ls -p, appends '\' postfix to KEY names + +Options for 'get' Action: + + -b, --binary print REG_BINARY data as hex bytes + -n, --none print data as stream of bytes as stored in registry + -x, --hex print numerical data as hex numbers + +Options for 'set' Action: + + -b, --binary set type to REG_BINARY (hex args or '-') + -D, --dword-be set type to REG_DWORD_BIG_ENDIAN + -e, --expand-string set type to REG_EXPAND_SZ + -i, --integer set type to REG_DWORD + -m, --multi-string set type to REG_MULTI_SZ + -n, --none set type to REG_NONE + -Q, --qword set type to REG_QWORD + -s, --string set type to REG_SZ + +Options for 'set' and 'unset' Actions: + + -K<c>, --key-separator[=]<c> set key separator to <c> instead of '\' + +Other Options: + + -h, --help output usage information and exit + -q, --quiet no error output, just nonzero return if KEY/VALUE missing + -v, --verbose verbose output, including VALUE contents when applicable + -w, --wow64 access 64 bit registry view (ignored on 32 bit Windows) + -W, --wow32 access 32 bit registry view (ignored on 32 bit Windows) + -V, --version output version information and exit + +KEY is in the format [host]\prefix\KEY\KEY\VALUE, where host is optional +remote host in either \\hostname or hostname: format and prefix is any of: + root HKCR HKEY_CLASSES_ROOT (local only) + config HKCC HKEY_CURRENT_CONFIG (local only) + user HKCU HKEY_CURRENT_USER (local only) + machine HKLM HKEY_LOCAL_MACHINE + users HKU HKEY_USERS + +You can use forward slash ('/') as a separator instead of backslash, in +that case backslash is treated as escape character +Example: regtool.exe get '\user\software\Microsoft\Clock\iFormat' + + + The regtool program allows shell scripts to access + and modify the Windows registry. Note that modifying the Windows registry + is dangerous, and carelessness here can result in an unusable system. Be + careful. + + The -v option means "verbose". For most commands, + this causes additional or lengthier messages to be printed. Conversely, + the -q option supresses error messages, so you can use + the exit status of the program to detect if a key exists or not (for + example). + + The -w option allows you to access the 64 bit view + of the registry. Several subkeys exist in a 32 bit and a 64 bit version + when running on Windows 64. Since Cygwin is running in 32 bit mode, it + only has access to the 32 bit view of these registry keys. When using the + -w switch, the 64 bit view is used and + regtool can access the entire registry. This option is + simply ignored when running on 32 bit Windows versions. + + The -W option allows you to access the 32 bit view + on the registry. The purpose of this option is mainly for symmetry. It + permits creation of OS agnostic scripts which would also work in a + hypothetical 64 bit version of Cygwin. + + You must provide regtool with an + action following options (if any). Currently, the + action must be add, set, + check, get, + list, remove, + set, or unset. + + The add action adds a new key. The + check action checks to see if a key exists (the exit + code of the program is zero if it does, nonzero if it does not). The + get action gets the value of a key, and prints it (and + nothing else) to stdout. Note: if the value doesn't exist, an error + message is printed and the program returns a non-zero exit code. If you + give -q, it doesn't print the message but does return + the non-zero exit code. + + The list action lists the subkeys and values + belonging to the given key. With list, the + -k option instructs regtool to + print only KEYs, and the -l option to print only + VALUEs. The -p option postfixes a + '/' to each KEY, but leave VALUEs with no postfix. The + remove action removes a key. Note that you may need to + remove everything in the key before you may remove it, but don't rely on + this stopping you from accidentally removing too much. + + The get action prints a value within a key. With + the -b option, data is printed as hex bytes. + -n allows to print the data as a typeless stream of + bytes. Integer values (REG_DWORD, REG_QWORD) are usually printed as + decimal values. The -x option allows to print the + numbers as hexadecimal values. + + The set action sets a value within a key. + -b means it's binary data (REG_BINARY). The binary + values are specified as hex bytes in the argument list. If the argument + is '-', binary data is read from stdin instead. + -d or -i means the value is a 32 + bit integer value (REG_DWORD). -D means the value is a + 32 bit integer value in Big Endian representation (REG_DWORD_BIG_ENDIAN). + -Q means the value is a 64 bit integer value + (REG_QWORD). -s means the value is a string (REG_SZ). + -e means it's an expanding string (REG_EXPAND_SZ) that + contains embedded environment variables. -m means it's + a multi-string (REG_MULTI_SZ). If you don't specify one of these, + regtool tries to guess the type based on the value you + give. If it looks like a number, it's a DWORD, unless it's value doesn't + fit into 32 bit, in which case it's a QWORD. If it starts with a percent, + it's an expanding string. If you give multiple values, it's a + multi-string. Else, it's a regular string. + + The unset action removes a value from a + key. + + The load action adds a new subkey and loads the + contents of a registry hive into it. The parent key must be + HKEY_LOCAL_MACHINE or HKEY_USERS. The unload action + unloads the file and removes the subkey. + + The save action saves a subkey into a registry + hive. + + By default, the last "\" or "/" is assumed to be the separator + between the key and the value. You can use the -K + option to provide an alternate key/value separator character. + + + + + setfacl + + +Usage: setfacl [-r] (-f ACL_FILE | -s acl_entries) FILE... + setfacl [-r] ([-d acl_entries] [-m acl_entries]) FILE... + +Modify file and directory access control lists (ACLs) + + -d, --delete delete one or more specified ACL entries + -f, --file set ACL entries for FILE to ACL entries read + from a ACL_FILE + -m, --modify modify one or more specified ACL entries + -r, --replace replace mask entry with maximum permissions + needed for the file group class + -s, --substitute substitute specified ACL entries for the + ACL of FILE + -h, --help output usage information and exit + -V, --version output version information and exit + +At least one of (-d, -f, -m, -s) must be specified + + + For each file given as parameter, setfacl will + either replace its complete ACL (-s, + -f), or it will add, modify, or delete ACL entries. + For more information on Cygwin and Windows ACLs, see see in the Cygwin User's Guide. + + Acl_entries are one or more comma-separated ACL entries from the + following list: + + u[ser]::perm + u[ser]:uid:perm + g[roup]::perm + g[roup]:gid:perm + m[ask]::perm + o[ther]::perm + + Default entries are like the above with the additional default + identifier. For example: + + d[efault]:u[ser]:uid:perm + + + perm is either a 3-char permissions string in + the form "rwx" with the character '-' for no + permission or it is the octal representation of the permissions, a value + from 0 (equivalent to "---") to 7 ("rwx"). uid is a + user name or a numerical uid. gid is a group name or + a numerical gid. + + The following options are supported: + + -d Delete one or more specified entries from the + file's ACL. The owner, group and others entries must not be deleted. + Acl_entries to be deleted should be specified without permissions, as in + the following list: + + u[ser]:uid + g[roup]:gid + d[efault]:u[ser]:uid + d[efault]:g[roup]:gid + d[efault]:m[ask]: + d[efault]:o[ther]: + + + -f Take the Acl_entries from ACL_FILE one per + line. Whitespace characters are ignored, and the character "#" may be + used to start a comment. The special filename "-" indicates reading from + stdin. Note that you can use this with getfacl and + setfacl to copy ACLs from one file to another: + +$ getfacl source_file | setfacl -f - target_file + + + Required entries are: one user entry for the owner of the file, one + group entry for the group of the file, and one other entry. + + If additional user and group entries are given: a mask entry for the + file group class of the file, and no duplicate user or group entries with + the same uid/gid. + + If it is a directory: one default user entry for the owner of the + file, one default group entry for the group of the file, one default mask + entry for the file group class, and one default other entry. + + -m Add or modify one or more specified ACL + entries. Acl_entries is a comma-separated list of entries from the same + list as above. + + -r Causes the permissions specified in the mask + entry to be ignored and replaced by the maximum permissions needed for + the file group class. + + -s Like -f, but substitute the + file's ACL with Acl_entries specified in a comma-separated list on the + command line. + + While the -d and -m options + may be used in the same command, the -f and + -s options may be used only exclusively. + + Directories may contain default ACL entries. Files created in a + directory that contains default ACL entries will have permissions + according to the combination of the current umask, the explicit + permissions requested and the default ACL entries + + Limitations: Under Cygwin, the default ACL entries are not taken + into account currently. + + + + + setmetamode + + +Usage: setmetamode [metabit|escprefix] + +Get or set keyboard meta mode + + Without argument, it shows the current meta key mode. + metabit|meta|bit The meta key sets the top bit of the character. + escprefix|esc|prefix The meta key sends an escape prefix. + +Other options: + + -h, --help This text + -V, --version Print program version and exit + + + setmetamode can be used to determine and set the + key code sent by the meta (aka Alt) key. + + + + + ssp + + +Usage: ssp [options] low_pc high_pc command... + +Single-step profile COMMAND + + -c, --console-trace trace every EIP value to the console. *Lots* slower. + -d, --disable disable single-stepping by default; use + OutputDebugString ("ssp on") to enable stepping + -e, --enable enable single-stepping by default; use + OutputDebugString ("ssp off") to disable stepping + -h, --help output usage information and exit + -l, --dll enable dll profiling. A chart of relative DLL usage + is produced after the run. + -s, --sub-threads trace sub-threads too. Dangerous if you have + race conditions. + -t, --trace-eip trace every EIP value to a file TRACE.SSP. This + gets big *fast*. + -v, --verbose output verbose messages about debug events. + -V, --version output version information and exit + +Example: ssp 0x401000 0x403000 hello.exe + + + SSP - The Single Step Profiler + + Original Author: DJ Delorie + + The SSP is a program that uses the Win32 debug API to run a program + one ASM instruction at a time. It records the location of each + instruction used, how many times that instruction is used, and all + function calls. The results are saved in a format that is usable by the + profiling program gprof, although + gprof will claim the values are seconds, they really + are instruction counts. More on that later. + + Because the SSP was originally designed to profile the Cygwin DLL, + it does not automatically select a block of code to report statistics on. + You must specify the range of memory addresses to keep track of manually, + but it's not hard to figure out what to specify. Use the "objdump" + program to determine the bounds of the target's ".text" section. Let's + say we're profiling cygwin1.dll. Make sure you've built it with debug + symbols (else gprof won't run) and run objdump like + this: +$ objdump -h cygwin1.dll + It will print a report + like this: + +cygwin1.dll: file format pei-i386 + +Sections: +Idx Name Size VMA LMA File off Algn + 0 .text 0007ea00 61001000 61001000 00000400 2**2 + CONTENTS, ALLOC, LOAD, READONLY, CODE, DATA + 1 .data 00008000 61080000 61080000 0007ee00 2**2 + CONTENTS, ALLOC, LOAD, DATA + . . . + + + The only information we're concerned with are the VMA of the .text + section and the VMA of the section after it (sections are usually + contiguous; you can also add the Size to the VMA to get the end address). + In this case, the VMA is 0x61001000 and the ending address is either + 0x61080000 (start of .data method) or 0x0x6107fa00 (VMA+Size method). + + There are two basic ways to use SSP - either profiling a whole + program, or selectively profiling parts of the program. + + To profile a whole program, just run ssp without + options. By default, it will step the whole program. Here's a simple + example, using the numbers above: + +$ ssp 0x61001000 0x61080000 hello.exe + This will step + the whole program. It will take at least 8 minutes on a PII/300 (yes, + really). When it's done, it will create a file called "gmon.out". You can + turn this data file into a readable report with gprof: + +$ gprof -b cygwin1.dll + The "-b" means 'skip the help + pages'. You can omit this until you're familiar with the report layout. + The gprof documentation explains a lot about this + report, but ssp changes a few things. For example, the + first part of the report reports the amount of time spent in each + function, like this: + +Each sample counts as 0.01 seconds. + % cumulative self self total + time seconds seconds calls ms/call ms/call name + 10.02 231.22 72.43 46 1574.57 1574.57 strcspn + 7.95 288.70 57.48 130 442.15 442.15 strncasematch + + The "seconds" columns are really CPU opcodes, 1/100 second per opcode. + So, "231.22" above means 23,122 opcodes. The ms/call values are 10x too + big; 1574.57 means 157.457 opcodes per call. Similar adjustments need to + be made for the "self" and "children" columns in the second part of the + report. + + OK, so now we've got a huge report that took a long time to + generate, and we've identified a spot we want to work on optimizing. + Let's say it's the time() function. We can use SSP to selectively profile + this function by using OutputDebugString() to control SSP from within the + program. Here's a sample program: + + #include <windows.h> + main() + { + time_t t; + OutputDebugString("ssp on"); + time(&t); + OutputDebugString("ssp off"); + } + + + Then, add the -d option to ssp to default to + *disabling* profiling. The program will run at full speed until the first + OutputDebugString, then step until the second. You can then use + gprof (as usual) to see the performance profile for + just that portion of the program's execution. + + There are many options to ssp. Since step-profiling makes your + program run about 1,000 times slower than normal, it's best to understand + all the options so that you can narrow down the parts of your program you + need to single-step. + + -v - verbose. This prints messages about threads + starting and stopping, OutputDebugString calls, DLLs loading, etc. + + -t and -c - tracing. With + -t, *every* step's address is written to the file + "trace.ssp". This can be used to help debug functions, since it can trace + multiple threads. Clever use of scripts can match addresses with + disassembled opcodes if needed. Warning: creates *huge* files, very + quickly. -c prints each address to the console, useful + for debugging key chunks of assembler. Use addr2line -C -f -s -e + foo.exe < trace.ssp > lines.ssp and then perl + cvttrace to convert to symbolic traces. + + -s - subthreads. Usually, you only need to trace + the main thread, but sometimes you need to trace all threads, so this + enables that. It's also needed when you want to profile a function that + only a subthread calls. However, using OutputDebugString automatically + enables profiling on the thread that called it, not the main thread. + + -l - dll profiling. Generates a pretty table of + how much time was spent in each dll the program used. No sense optimizing + a function in your program if most of the time is spent in the DLL. I + usually use the -v, -s, and + -l options: + +$ ssp -v -s -l -d 0x61001000 0x61080000 hello.exe + + + + + + strace + + +Usage: strace.exe [OPTIONS] <command-line> +Usage: strace.exe [OPTIONS] -p <pid> + +Trace system calls and signals + + -b, --buffer-size=SIZE set size of output file buffer + -d, --no-delta don't display the delta-t microsecond timestamp + -f, --trace-children trace child processes (toggle - default true) + -h, --help output usage information and exit + -m, --mask=MASK set message filter mask + -n, --crack-error-numbers output descriptive text instead of error + numbers for Windows errors + -o, --output=FILENAME set output file to FILENAME + -p, --pid=n attach to executing program with cygwin pid n + -q, --quiet toggle "quiet" flag. Defaults to on if "-p", + off otherwise. + -S, --flush-period=PERIOD flush buffered strace output every PERIOD secs + -t, --timestamp use an absolute hh:mm:ss timestamp insted of + the default microsecond timestamp. Implies -d + -T, --toggle toggle tracing in a process already being + traced. Requires -p <pid> + -u, --usecs toggle printing of microseconds timestamp + -V, --version output version information and exit + -w, --new-window spawn program under test in a new window + + MASK can be any combination of the following mnemonics and/or hex values + (0x is optional). Combine masks with '+' or ',' like so: + + --mask=wm+system,malloc+0x00800 + + Mnemonic Hex Corresponding Def Description + ========================================================================= + all 0x000001 (_STRACE_ALL) All strace messages. + flush 0x000002 (_STRACE_FLUSH) Flush output buffer after each message. + inherit 0x000004 (_STRACE_INHERIT) Children inherit mask from parent. + uhoh 0x000008 (_STRACE_UHOH) Unusual or weird phenomenon. + syscall 0x000010 (_STRACE_SYSCALL) System calls. + startup 0x000020 (_STRACE_STARTUP) argc/envp printout at startup. + debug 0x000040 (_STRACE_DEBUG) Info to help debugging. + paranoid 0x000080 (_STRACE_PARANOID) Paranoid info. + termios 0x000100 (_STRACE_TERMIOS) Info for debugging termios stuff. + select 0x000200 (_STRACE_SELECT) Info on ugly select internals. + wm 0x000400 (_STRACE_WM) Trace Windows msgs (enable _strace_wm). + sigp 0x000800 (_STRACE_SIGP) Trace signal and process handling. + minimal 0x001000 (_STRACE_MINIMAL) Very minimal strace output. + pthread 0x002000 (_STRACE_PTHREAD) Pthread calls. + exitdump 0x004000 (_STRACE_EXITDUMP) Dump strace cache on exit. + system 0x008000 (_STRACE_SYSTEM) Serious error; goes to console and log. + nomutex 0x010000 (_STRACE_NOMUTEX) Don't use mutex for synchronization. + malloc 0x020000 (_STRACE_MALLOC) Trace malloc calls. + thread 0x040000 (_STRACE_THREAD) Thread-locking calls. + special 0x100000 (_STRACE_SPECIAL) Special debugging printfs for + non-checked-in code + + + The strace program executes a program, and + optionally the children of the program, reporting any Cygwin DLL output + from the program(s) to stdout, or to a file with the + -o option. With the -w option, you + can start an strace session in a new window, for example: + +$ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' & + + This is particularly useful for strace sessions that + take a long time to complete. + + Note that strace is a standalone Windows program + and so does not rely on the Cygwin DLL itself (you can verify this with + cygcheck). As a result it does not understand + symlinks. This program is mainly useful for debugging the Cygwin DLL + itself. + + + + + tzset + + +Usage: tzset [OPTION] + +Print POSIX-compatible timezone ID from current Windows timezone setting + +Options: + -h, --help output usage information and exit. + -V, --version output version information and exit. + +Use tzset to set your TZ variable. In POSIX-compatible shells like bash, +dash, mksh, or zsh: + + export TZ=$(tzset) + +In csh-compatible shells like tcsh: + + setenv TZ `tzset` + + + The tzset tool reads the current timezone from + Windows and generates a POSIX-compatible timezone information for the TZ + environment variable from that information. That's all there is to it. + For the way how to use it, see the above usage information. + + + + + umount + + +Usage: umount.exe [OPTION] [<posixpath>] + +Unmount filesystems + + -h, --help output usage information and exit + -U, --remove-user-mounts remove all user mounts + -V, --version output version information and exit + + + The umount program removes mounts from the mount + table in the current session. If you specify a POSIX path that + corresponds to a current mount point, umount will + remove it from the current mount table. Note that you can only remove + user mount points. The -U flag may be used to specify + removing all user mount points from the current user session. + + See for more information on the mount + table. + + +