From a2a7aa3f4ce1e11a6b97943bb44419d05d6f6580 Mon Sep 17 00:00:00 2001 From: Warren Young Date: Fri, 10 May 2013 15:58:48 +0000 Subject: [PATCH] - Added and tags to the top of utils.xml and pretty- printed it. - Removed obsolete utils.sgml - Added a ChangeLog entry for this replacement, which partially took place days ago. This checkin formalizes the switch from SGML to DocBook XML for this file. --- winsup/utils/ChangeLog | 6 + winsup/utils/utils.sgml | 2190 --------------------------------------- winsup/utils/utils.xml | 2159 ++++++++++++++++++-------------------- 3 files changed, 1036 insertions(+), 3319 deletions(-) delete mode 100644 winsup/utils/utils.sgml diff --git a/winsup/utils/ChangeLog b/winsup/utils/ChangeLog index b71cb49c7..764285fc6 100644 --- a/winsup/utils/ChangeLog +++ b/winsup/utils/ChangeLog @@ -1,3 +1,9 @@ +2013-05-10 Warren Young + + * utils.sgml utils.xml: Renamed utils.sgml to utils.xml, added + and tags to the top, and formatted it. No + content change. + 2013-04-23 Corinna Vinschen * Merge in cygwin-64bit-branch. See ChangeLog.64bit for details. diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml deleted file mode 100644 index 8c0b838c6..000000000 --- a/winsup/utils/utils.sgml +++ /dev/null @@ -1,2190 +0,0 @@ -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] - - - - -mkgroup - - -Usage: mkgroup [OPTION]... - -Print /etc/group file to stdout - -Options: - - -l,--local [machine[,offset]] - print local groups with gid offset offset - (from local machine if no machine specified) - -L,--Local [machine[,offset]] - ditto, but generate groupname with machine prefix - -d,--domain [domain[,offset]] - print domain groups with gid offset offset - (from current domain if no domain specified) - -D,--Domain [domain[,offset]] - ditto, but generate groupname with machine prefix - -c,--current print current group - -C,--Current ditto, but generate groupname with machine or - domain prefix - -S,--separator char for -L, -D, -C use character char as domain\group - separator in groupname instead of the default '\' - -o,--id-offset offset change the default offset (10000) added to gids - in domain or foreign server accounts. - -g,--group groupname only return information for the specified group - one of -l, -L, -d, -D must be specified, too - -b,--no-builtin don't print BUILTIN groups - -U,--unix grouplist additionally print UNIX groups when using -l or -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!) - -s,--no-sids (ignored) - -u,--users (ignored) - -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 help -configure Cygwin by creating a /etc/group -file. Its use is essential to include Windows security information. - -The command is initially called by setup.exe to -create a default /etc/group. This should be -sufficient in most circumstances. However, especially when working -in a multi-domain environment, you can use mkgroup -manually to create a more complete /etc/group file for -all domains. Especially when you have the same group name used on -multiple machines or in multiple domains, you can use the -D, --L and -C options to create unique -domain\group style groupnames. - -Note that this information is static. If you change the group -information in your system, you'll need to regenerate the group file -for it to have the new information. - -The -d/-D and -l/-L options -allow you to specify where the information comes from, the -local SAM of a machine or from the domain, or both. -With the -d/-D options the program contacts a Domain -Controller, which my be unreachable or have restricted access. -Comma-separated from the machine or domain, you can specify an offset -which is used as base added to the group's RID to compute the gid -(offset + RID = gid). This allows you to create the same gids every time you -re-run mkgroup. -For very simple needs, an entry for the current user's group can be -created by using the option -c or -C. -If you want to use one of the -D, -L -or -C options, but you don't like the backslash as -domain/group separator, you can specify another separator using the --S option, for instance: - -Setting up group entry for current user with different domain/group separator - -$ mkgroup -C -S+ > /etc/group -$ cat /etc/group -DOMAIN+my_group:S-1-5-21-2913048732-1697188782-3448811101-1144:11144: - - - -The -o option allows for special cases -(such as multiple domains) 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]... - -Print /etc/passwd file to stdout - -Options: - - -l,--local [machine[,offset]] - print local user accounts with uid offset offset - (from local machine if no machine specified) - -L,--Local [machine[,offset]] - ditto, but generate username with machine prefix - -d,--domain [domain[,offset]] - print domain accounts with uid offset offset - (from current domain if no domain specified) - -D,--Domain [domain[,offset]] - ditto, but generate username with domain prefix - -c,--current print current user - -C,--Current ditto, but generate username with machine or - domain prefix - -S,--separator char for -L, -D, -C use character char as domain\user - separator in username instead of the default '\' - -o,--id-offset offset change the default offset (10000) added to uids - in domain or foreign server accounts. - -u,--username username only return information for the specified user - one of -l, -L, -d, -D must be specified, too - -p,--path-to-home path use specified path instead of user account home dir - or /home prefix - -U,--unix userlist additionally print UNIX users when using -l or -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!) - -s,--no-sids (ignored) - -m,--no-mount (ignored) - -g,--local-groups (ignored) - -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 help -configure Cygwin by creating a /etc/passwd from -your system information. -Its use is essential to include Windows security information. However, -the actual passwords are determined by Windows, not by the content of -/etc/passwd. - -The command is initially called by setup.exe to -create a default /etc/passwd. This should be -sufficient in most circumstances. However, especially when working -in a multi-domain environment, you can use mkpasswd -manually to create a more complete /etc/passwd file for -all domains. Especially when you have the same user name used on -multiple machines or in multiple domains, you can use the -D, --L and -C options to create unique -domain\user style usernames. - -Note that this information is static. If you change the user -information in your system, you'll need to regenerate the passwd file -for it to have the new information. - -The -d/-D and -l/-L options -allow you to specify where the information comes from, the -local machine or the domain (default or given), or both. -With the -d/-D options the program contacts the Domain -Controller, which may be unreachable or have restricted access. -Comma-separated from the machine or domain, you can specify an offset -which is used as base added to the user's RID to compute the uid -(offset + RID = uid). This allows to create the same uids every time you -re-run mkpasswd. -An entry for the current user can be created by using the -option -c or -C. -If you want to use one of the -D, -L -or -C options, but you don't like the backslash as -domain/group separator, you can specify another separator using the --S option, similar to the mkgroup. -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 DAYS set system minimum password age to DAYS days. - -x, --maxage DAYS set system maximum password age to DAYS 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. - - - diff --git a/winsup/utils/utils.xml b/winsup/utils/utils.xml index 8c0b838c6..f3539239a 100644 --- a/winsup/utils/utils.xml +++ b/winsup/utils/utils.xml @@ -1,18 +1,22 @@ -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. - + + Cygwin Utilities -cygcheck + 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] @@ -65,43 +69,39 @@ Note: -c, -f, and -l only report on packages that are currently installed. To 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 - + 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 @@ -112,43 +112,43 @@ $ cygcheck -l less /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 -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 -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. + 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. + 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 - + 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'. @@ -166,72 +166,68 @@ 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. + 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. + 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. + 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: + 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 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. - + 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: + 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 @@ -241,32 +237,33 @@ 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 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 + 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. + 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 + + cygpath - + Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME... cygpath [-c HANDLE] cygpath [-ADHOPSW] @@ -316,71 +313,80 @@ Other options: -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 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. + 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. - + 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 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 -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 -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. - + 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 - + + 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. + 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 + + dumper - + Usage: dumper [OPTION] FILENAME WIN32PID Dump core from WIN32PID to FILENAME.core @@ -428,45 +433,40 @@ Dump core from WIN32PID to FILENAME.core -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 - - + 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. -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. - -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. - -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 -getconf - - + Usage: getconf [-v specification] variable_name [pathname] getconf -a [pathname] @@ -482,39 +482,39 @@ Other options: -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. - + 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 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. + 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. + Use the -a option to print a list of all available + configuration variables for the system, or given + pathname, and their values. - + -getfacl + + getfacl - + Usage: getfacl [-adn] FILE [FILE2...] Display file and directory access control lists (ACLs). @@ -531,16 +531,15 @@ 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: - + 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 @@ -557,12 +556,13 @@ The format for ACL output is as follows: default:mask:perm default:other:perm - - + + -kill + + kill - + Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...] kill -l [signal] @@ -575,56 +575,53 @@ Send signals to processes -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. + 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 - - + 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. -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. -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. -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: -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 - + + 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. + 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 @@ -661,11 +658,12 @@ SIGUSR1 30 user defined signal 1 SIGUSR2 31 user defined signal 2 - + -ldd + + ldd - + Usage: ldd [OPTION]... FILE... Print shared library dependencies @@ -680,14 +678,16 @@ Print shared library dependencies (currently unimplemented) -ldd prints the shared libraries (DLLs) an executable -or DLL is linked against. No modifying option is implemented yet. + ldd prints the shared libraries (DLLs) an + executable or DLL is linked against. No modifying option is implemented + yet. - + -locale + + locale - + Usage: locale [-amvhV] or: locale [-ck] NAME or: locale [-usfnU] @@ -720,27 +720,27 @@ Other options: -V, --version Print program version and exit -locale without parameters prints information about -the current locale environment settings. + 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, -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". + 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: + Usage example: - + bash$ export LANG=$(locale -uU) bash$ echo $LANG en_US.UTF-8 @@ -749,11 +749,11 @@ 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: + 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 @@ -774,10 +774,10 @@ catalan ... -The -v option prints more detailed information about -each available locale. Example: + 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 ------------------------------------------------------------------------------- @@ -808,18 +808,18 @@ territory | Spain ... -The -m option prints the names of the available -charmaps supported by Cygwin to stdout. + 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: + 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]" @@ -831,11 +831,12 @@ bash$ locale noexpr ^[nN] - + -mkgroup + + mkgroup - + Usage: mkgroup [OPTION]... Print /etc/group file to stdout @@ -876,63 +877,64 @@ 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 help -configure Cygwin by creating a /etc/group -file. Its use is essential to include Windows security information. + The mkgroup program can be used to help configure + Cygwin by creating a /etc/group file. Its use is + essential to include Windows security information. -The command is initially called by setup.exe to -create a default /etc/group. This should be -sufficient in most circumstances. However, especially when working -in a multi-domain environment, you can use mkgroup -manually to create a more complete /etc/group file for -all domains. Especially when you have the same group name used on -multiple machines or in multiple domains, you can use the -D, --L and -C options to create unique -domain\group style groupnames. - -Note that this information is static. If you change the group -information in your system, you'll need to regenerate the group file -for it to have the new information. + The command is initially called by setup.exe to + create a default /etc/group. This should be + sufficient in most circumstances. However, especially when working in a + multi-domain environment, you can use mkgroup manually + to create a more complete /etc/group file for all + domains. Especially when you have the same group name used on multiple + machines or in multiple domains, you can use the -D, + -L and -C options to create unique + domain\group style groupnames. -The -d/-D and -l/-L options -allow you to specify where the information comes from, the -local SAM of a machine or from the domain, or both. -With the -d/-D options the program contacts a Domain -Controller, which my be unreachable or have restricted access. -Comma-separated from the machine or domain, you can specify an offset -which is used as base added to the group's RID to compute the gid -(offset + RID = gid). This allows you to create the same gids every time you -re-run mkgroup. -For very simple needs, an entry for the current user's group can be -created by using the option -c or -C. -If you want to use one of the -D, -L -or -C options, but you don't like the backslash as -domain/group separator, you can specify another separator using the --S option, for instance: + Note that this information is static. If you change the group + information in your system, you'll need to regenerate the group file for + it to have the new information. -Setting up group entry for current user with different domain/group separator - + The -d/-D and -l/-L options + allow you to specify where the information comes from, the local SAM of a + machine or from the domain, or both. With the -d/-D + options the program contacts a Domain Controller, which my be unreachable + or have restricted access. Comma-separated from the machine or domain, + you can specify an offset which is used as base added to the group's RID + to compute the gid (offset + RID = gid). This allows you to create the + same gids every time you re-run mkgroup. For very + simple needs, an entry for the current user's group can be created by + using the option -c or -C. If you + want to use one of the -D, -L or + -C options, but you don't like the backslash as + domain/group separator, you can specify another separator using the + -S option, for instance: + + + Setting up group entry for current user with different + domain/group separator + $ mkgroup -C -S+ > /etc/group $ cat /etc/group DOMAIN+my_group:S-1-5-21-2913048732-1697188782-3448811101-1144:11144: - + -The -o option allows for special cases -(such as multiple domains) 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. - + The -o option allows for special cases (such as + multiple domains) 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 + + mkpasswd - + Usage: mkpasswd [OPTIONS]... Print /etc/passwd file to stdout @@ -975,69 +977,63 @@ 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 help -configure Cygwin by creating a /etc/passwd from -your system information. -Its use is essential to include Windows security information. However, -the actual passwords are determined by Windows, not by the content of -/etc/passwd. + The mkpasswd program can be used to help configure + Cygwin by creating a /etc/passwd from your system + information. Its use is essential to include Windows security + information. However, the actual passwords are determined by Windows, not + by the content of /etc/passwd. -The command is initially called by setup.exe to -create a default /etc/passwd. This should be -sufficient in most circumstances. However, especially when working -in a multi-domain environment, you can use mkpasswd -manually to create a more complete /etc/passwd file for -all domains. Especially when you have the same user name used on -multiple machines or in multiple domains, you can use the -D, --L and -C options to create unique -domain\user style usernames. - -Note that this information is static. If you change the user -information in your system, you'll need to regenerate the passwd file -for it to have the new information. + The command is initially called by setup.exe to + create a default /etc/passwd. This should be + sufficient in most circumstances. However, especially when working in a + multi-domain environment, you can use mkpasswd + manually to create a more complete /etc/passwd file + for all domains. Especially when you have the same user name used on + multiple machines or in multiple domains, you can use the + -D, -L and -C + options to create unique domain\user style usernames. -The -d/-D and -l/-L options -allow you to specify where the information comes from, the -local machine or the domain (default or given), or both. -With the -d/-D options the program contacts the Domain -Controller, which may be unreachable or have restricted access. -Comma-separated from the machine or domain, you can specify an offset -which is used as base added to the user's RID to compute the uid -(offset + RID = uid). This allows to create the same uids every time you -re-run mkpasswd. -An entry for the current user can be created by using the -option -c or -C. -If you want to use one of the -D, -L -or -C options, but you don't like the backslash as -domain/group separator, you can specify another separator using the --S option, similar to the mkgroup. -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: + Note that this information is static. If you change the user + information in your system, you'll need to regenerate the passwd file for + it to have the new information. -Using an alternate home root - + The -d/-D and -l/-L options + allow you to specify where the information comes from, the local machine + or the domain (default or given), or both. With the + -d/-D options the program contacts the Domain + Controller, which may be unreachable or have restricted access. + Comma-separated from the machine or domain, you can specify an offset + which is used as base added to the user's RID to compute the uid (offset + + RID = uid). This allows to create the same uids every time you re-run + mkpasswd. An entry for the current user can be created + by using the option -c or -C. If + you want to use one of the -D, -L + or -C options, but you don't like the backslash as + domain/group separator, you can specify another separator using the + -S option, similar to the mkgroup. + 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. -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 -mount - - + Usage: mount [OPTION] [<win32path> <posixpath>] mount -a mount <posixpath> @@ -1056,24 +1052,25 @@ Display information about mounted filesystems, or mount a filesystem -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 + 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 + + Using mount -If you just type mount with no parameters, it -will display the current mount table for you. + If you just type mount with no parameters, it + will display the current mount table for you. - -Displaying the current set of mount points - + + 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) @@ -1081,24 +1078,23 @@ 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. + 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. - + 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 - + + Adding mount points + $ ls /data ls: /data: No such file or directory $ mount //pollux/home/joe/data /data @@ -1111,22 +1107,23 @@ 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. + 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): + 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). @@ -1159,137 +1156,135 @@ most of the options are duplicates of other mount flags): text - Files default to CRLF text mode line endings. -For a more complete description of the mount options and the -/etc/fstab file, see -. + 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. + 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. + 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. + 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. + 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. + 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. + 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. + 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 + + 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: + 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 - + + 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) + 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 - + + Changing the default prefix with specific mount options + $ mount -c /mnt -o binary,noacl - + - + -Limitations + + 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. + 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. - + 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. - + 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 + + passwd - + Usage: passwd [OPTION] [USER] Change USER's password or password attributes. @@ -1338,107 +1333,104 @@ 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. + 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. + 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. + 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. + 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. - + 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'. + 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. - + 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 -. + 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. + 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. + Limitations: Users may not be able to change their password on some + systems. - + -pldd + + pldd - + Usage: pldd [OPTION...] PID List dynamic shared objects loaded into a process. @@ -1448,14 +1440,15 @@ List dynamic shared objects loaded into a process. -V, --version Print program version -pldd prints the shared libraries (DLLs) loaded -by the process with the given PID. + pldd prints the shared libraries (DLLs) loaded by + the process with the given PID. - + -ps + + ps - + Usage: ps [-aefls] [-u UID] Report process status @@ -1473,51 +1466,46 @@ Report process status 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 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. - + 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. - + 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 + + regtool - + Usage: regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY View or edit the Win32 registry @@ -1584,112 +1572,102 @@ 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 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 -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 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. + 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. - + 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 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 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 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 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 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 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. - + 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. - + 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 + + setfacl - + Usage: setfacl [-r] (-f ACL_FILE | -s acl_entries) FILE... setfacl [-r] ([-d acl_entries] [-m acl_entries]) FILE... @@ -1709,18 +1687,15 @@ Modify file and directory access control lists (ACLs) 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. - + 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: - + Acl_entries are one or more comma-separated ACL entries from the + following list: + u[ser]::perm u[ser]:uid:perm g[roup]::perm @@ -1728,119 +1703,84 @@ from the following list: m[ask]::perm o[ther]::perm -Default entries are like the above with the additional -default identifier. For example: - + 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. - + 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: - + 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: - + -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: - + -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. - + 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 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. - + 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. - + -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. - + -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. - + -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. - + 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 - + 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. - + Limitations: Under Cygwin, the default ACL entries are not taken + into account currently. - + -setmetamode + + setmetamode - + Usage: setmetamode [metabit|escprefix] Get or set keyboard meta mode @@ -1855,14 +1795,15 @@ Other options: -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. + setmetamode can be used to determine and set the + key code sent by the meta (aka Alt) key. - + -ssp + + ssp - + Usage: ssp [options] low_pc high_pc command... Single-step profile COMMAND @@ -1885,40 +1826,30 @@ Single-step profile COMMAND Example: ssp 0x401000 0x403000 hello.exe - -SSP - The Single Step Profiler - + SSP - The Single Step Profiler - -Original Author: DJ Delorie - + 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. - + 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: - - + 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: - + It will print a report + like this: + cygwin1.dll: file format pei-i386 Sections: @@ -1928,71 +1859,53 @@ Idx Name Size VMA LMA File off Algn 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). - + 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. - + 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: - - + 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: - - + 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: - - + 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. -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: - - + 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() { @@ -2001,65 +1914,53 @@ program. Here's a sample program: 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. - + 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. - + 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. - + -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. - + -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. - + -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: - - + -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 + + strace - + Usage: strace.exe [OPTIONS] <command-line> Usage: strace.exe [OPTIONS] -p <pid> @@ -2115,30 +2016,29 @@ Trace system calls and signals 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: - - + 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. - + 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. + 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 + + tzset - + Usage: tzset [OPTION] Print POSIX-compatible timezone ID from current Windows timezone setting @@ -2157,16 +2057,17 @@ 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. + 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 + + umount - + Usage: umount.exe [OPTION] [<posixpath>] Unmount filesystems @@ -2176,15 +2077,15 @@ Unmount filesystems -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. + 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. - + See for more information on the mount + table. +