diff options
Diffstat (limited to 'winsup/utils/utils.xml')
| -rw-r--r-- | winsup/utils/utils.xml | 2127 |
1 files changed, 0 insertions, 2127 deletions
diff --git a/winsup/utils/utils.xml b/winsup/utils/utils.xml deleted file mode 100644 index b7e8ff81d..000000000 --- a/winsup/utils/utils.xml +++ /dev/null @@ -1,2127 +0,0 @@ -<?xml version="1.0" encoding='UTF-8'?> -<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> - -<sect1 id="using-utils"> - <title>Cygwin Utilities</title> - - <para>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, <literal>--help</literal> and <literal>-h</literal> function - identically. All of the Cygwin command-line utilities support the - <literal>--help</literal> and <literal>--version</literal> options. </para> - - <sect2 id="cygcheck"> - <title>cygcheck</title> - - <screen> -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. -</screen> - - <para> The <command>cygcheck</command> program is a diagnostic utility for - dealing with Cygwin programs. If you are familiar with - <command>dpkg</command> or <command>rpm</command>, - <command>cygcheck</command> is similar in many ways. (The major - difference is that <command>setup.exe</command> handles installing and - uninstalling packages; see <xref linkend="internet-setup"/> for more - information.) </para> - <para> The <literal>-c</literal> option checks the version and status of - installed Cygwin packages. If you specify one or more package names, - <command>cygcheck</command> will limit its output to those packages, or - with no arguments it lists all packages. A package will be marked - <literal>Incomplete</literal> if files originally installed are no longer - present. The best thing to do in that situation is reinstall the package - with <command>setup.exe</command>. To see which files are missing, use - the <literal>-v</literal> option. If you do not need to know the status - of each package and want <command>cygcheck</command> to run faster, add - the <literal>-d</literal> option and <command>cygcheck</command> will - only output the name and version for each package. </para> - <para> If you list one or more programs on the command line, - <command>cygcheck</command> 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 <literal>-s</literal> option, - <command>cygcheck</command> will give general system information. If you - list one or more programs on the command line and specify - <literal>-s</literal>, <command>cygcheck</command> will report on - both.</para> - <para> The <literal>-f</literal> option helps you to track down which - package a file came from, and <literal>-l</literal> lists all files in a - package. For example, to find out about - <filename>/usr/bin/less</filename> and its package: <example - id="utils-cygcheck-ex"><title>Example <command>cygcheck</command> - usage</title> - <screen> -$ 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 -</screen> - </example> </para> - - <para>The <literal>-h</literal> 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.</para> - - <para>The <literal>-v</literal> 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. </para> - - <para>The <literal>-r</literal> option causes <command>cygcheck</command> - 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.</para> - - <para>In contrast to the other options that search the packages that are - installed on your local system, the <literal>-p</literal> 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 <literal>cygwin.com</literal> web site. In fact, it is - equivalent to the search that is available on the <ulink - url="http://cygwin.com/packages/">Cygwin package listing</ulink> - page.</para> - - <para>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: - <example id="utils-search-ex"><title>Searching all packages for a - file</title> - <screen> -$ 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) -</screen> - </example> </para> - - <para>Note that this option takes a regular expression, not a glob or - wildcard. This means that you need to use <literal>.*</literal> if you - want something similar to the wildcard <literal>*</literal> commonly used - in filename globbing. Similarly, to match the period character you should - use <literal>\.</literal> since the <literal>.</literal> character in a - regexp is a metacharacter that will match any character. Also be aware - that the characters such as <literal>\</literal> and <literal>*</literal> - are shell metacharacters, so they must be either escaped or quoted, as in - the example above.</para> - - <para>The third example above illustrates that if you want to match a whole - filename, you should include the <literal>/</literal> path seperator. In - the given example this ensures that filenames that happen to end in - <literal>ls.exe</literal> such as <literal>ncftpls.exe</literal> are not - shown. Note that this use does not mean "look for packages with - <literal>ls</literal> in the root directory," since the - <literal>/</literal> can match anywhere in the path. It's just there to - anchor the match so that it matches a full filename.</para> - - <para>By default the matching is case-sensitive. To get a case insensitive - match, begin your regexp with <literal>(?i)</literal> which is a - PCRE-specific feature. For complete documentation on Perl-compatible - regular expression syntax and options, read the <command>perlre</command> - manpage, or one of many websites such as <literal>perldoc.com</literal> - that document the Perl language.</para> - - <para>The <command>cygcheck</command> 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:</para> - - <screen> -<prompt>$</prompt> <userinput>cygcheck -s -v -r -h > cygcheck_output.txt</userinput> -</screen> - - <para> 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 <command>cygcheck - --delete-orphaned-installation-keys</command> command.</para> - - <para> 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. </para> - - <para> 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:</para> - - <screen> -*** 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. -</screen> - - <para> To disable the usage of a unique key value of a certain Cygwin DLL, - use the <command>cygcheck --disable-unique-object-names - Cygwin-DLL</command> command. <literal>Cygwin-DLL</literal> 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 <command>cygcheck</command> from a DOS command line for - this purpose.</para> - - <para>To re-enable the usage of a unique key, use the <command>cygcheck - --enable-unique-object-names Cygwin-DLL</command> command. This option - has the same characteristics as the - <literal>--disable-unique-object-names</literal> option</para> - - <para>Finally, you can use <command>cygcheck --show-unique-object-names - Cygwin-DLL</command> to find out if the given Cygwin DLL use unique - object names or not. In contrast to the <literal>--disable-...</literal> - and <literal>--enable-...</literal> options, the - <literal>--show-unique-object-names</literal> option also works for - Cygwin DLLs which are currently in use.</para> - - </sect2> - - <sect2 id="cygpath"> - <title>cygpath</title> - - <screen> -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 -</screen> - - <para>The <command>cygpath</command> 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, <command>cygpath</command> can output - information about the location of important system directories in either - format. </para> - - <para>The <literal>-u</literal> and <literal>-w</literal> options indicate - whether you want a conversion to UNIX (POSIX) format - (<literal>-u</literal>) or to Windows format (<literal>-w</literal>). Use - the <literal>-d</literal> to get DOS-style (8.3) file and path names. The - <literal>-m</literal> 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.</para> - - <para> In combination with the <literal>-w</literal> option, you can use - the <literal>-l</literal> and <literal>-s</literal> options to use normal - (long) or DOS-style (short) form. The <literal>-d</literal> option is - identical to <literal>-w</literal> and <literal>-s</literal> together. </para> - - <para>The <literal>-C</literal> option allows to specify a Windows codepage - to print DOS and Windows paths created with one of the - <literal>-d</literal>, <literal>-m</literal>, or <literal>-w</literal> - options. The default is to use the character set of the current locale - defined by one of the internationalization environment variables - <envar>LC_ALL</envar>, <envar>LC_CTYPE</envar>, or <envar>LANG</envar>, - see <xref linkend="setup-locale"/>. 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.</para> - - <para>The <literal>-C</literal> option takes a single parameter:</para> - <itemizedlist spacing="compact"> - <listitem> - <para><literal>ANSI</literal>, to specify the current ANSI - codepage</para> - </listitem> - <listitem> - <para><literal>OEM</literal>, to specify the current OEM (console) - codepage</para> - </listitem> - <listitem> - <para><literal>UTF8</literal>, to specify UTF-8.</para> - </listitem> - <listitem> - <para>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 <ulink - url="http://msdn.microsoft.com/en-us/library/dd317756(VS.85).aspx" - >Code Page Identifiers</ulink>. A codepage of 0 is the same as if the - <literal>-C</literal> hasn't been specified at all.</para> - </listitem> - </itemizedlist> - - <para>The <literal>-p</literal> 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 <literal>-p</literal> you are - instructing <command>cygpath</command> to convert between these - formats.</para> - - <para>The <literal>-i</literal> 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 <command>cygpath</command> output may contain spaces (C:\Program - Files) so should be enclosed in quotes. </para> - - - <example id="utils-cygpath-ex"> - <title>Example <command>cygpath</command> usage</title> - <screen> -<![CDATA[ -#!/bin/sh -if [ "${1}" = "" ]; - then - XPATH="."; - else - XPATH="$(cygpath -C ANSI -w "${1}")"; -fi -explorer $XPATH & -]]> -</screen> - </example> - - <para>The capital options <literal>-D</literal>, <literal>-H</literal>, - <literal>-P</literal>, <literal>-S</literal>, and <literal>-W</literal> - output directories used by Windows that are not the same on all systems, - for example <literal>-S</literal> might output C:\WINNT\system32 or - C:\Windows\System32. The <literal>-H</literal> shows the Windows profiles - directory that can be used as root of home. The <literal>-A</literal> - option forces use of the "All Users" directories instead of the current - user for the <literal>-D</literal>, <literal>-O</literal> and - <literal>-P</literal> options. The <literal>-F</literal> 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 - <literal>-w</literal> or <literal>-d</literal> options to get other - formats.</para> - - </sect2> - - <sect2 id="dumper"> - <title>dumper</title> - - <screen> -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 -</screen> - - <para>The <command>dumper</command> utility can be used to create a core - dump of running Windows process. This core dump can be later loaded to - <command>gdb</command> and analyzed. One common way to use - <command>dumper</command> is to plug it into cygwin's Just-In-Time - debugging facility by adding - <screen> -error_start=x:\path\to\dumper.exe -</screen> to the - <emphasis>CYGWIN</emphasis> environment variable. Please note that - <literal>x:\path\to\dumper.exe</literal> is Windows-style and not cygwin - path. If <literal>error_start</literal> is set this way, then dumper will - be started whenever some program encounters a fatal error. </para> - - <para> <command>dumper</command> 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 - <command>dumper</command> exits, the target process is terminated too. </para> - - <para> To save space in the core dump, <command>dumper</command> 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, <command>dumper</command> 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. </para> - - </sect2> - - <sect2 id="getconf"> - <title>getconf</title> - - <screen> -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 -</screen> - - <para>The <command>getconf</command> utility prints the value of the - configuration variable specified by <literal>variable_name</literal>. If - no <literal>pathname</literal> is given, <command>getconf</command> - serves as a wrapper for the <literal>confstr</literal> and - <literal>sysconf</literal> functions, supporting the symbolic constants - defined in the <literal>limits.h</literal> and - <literal>unistd.h</literal> headers, without their respective - <literal>_CS_</literal> or <literal>_SC_</literal> prefixes. </para> - - <para>If <literal>pathname</literal> is given, <command>getconf</command> - prints the value of the configuration variable for the specified - pathname. In this form, <command>getconf</command> serves as a wrapper - for the <literal>pathconf</literal> function, supporting the symbolic - constants defined in the <literal>unistd.h</literal> header, without the - <literal>_PC_</literal> prefix. </para> - - <para>If you specify the <literal>-v</literal> 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 <literal>POSIX_V7_ILP32_OFFBIG</literal> and the legacy - <literal>POSIX_V6_ILP32_OFFBIG</literal> and - <literal>XBS5_ILP32_OFFBIG</literal> equivalents.</para> - - <para>Use the <literal>-a</literal> option to print a list of all available - configuration variables for the system, or given - <literal>pathname</literal>, and their values.</para> - - </sect2> - - <sect2 id="getfacl"> - <title>getfacl</title> - - <screen> -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. -</screen> - - <para> For each argument that is a regular file, special file or directory, - <command>getfacl</command> displays the owner, the group, and the ACL. - For directories <command>getfacl</command> displays additionally the - default ACL. With no options specified, <command>getfacl</command> - 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 <xref linkend="ntsec"/> in the Cygwin User's Guide. The format - for ACL output is as follows: - <screen> - # 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 -</screen> - </para> - </sect2> - - <sect2 id="kill"> - <title>kill</title> - - <screen> -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 -</screen> - - <para>The <command>kill</command> 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.</para> - - <para>You may need to specify the full path to use <command>kill</command> - from within some shells, including <command>bash</command>, the default - Cygwin shell. This is because <command>bash</command> defines a - <command>kill</command> builtin function; see the <command>bash</command> - man page under <emphasis>BUILTIN COMMANDS</emphasis> for more - information. To make sure you are using the Cygwin version, try - <screen> -$ /bin/kill --version -</screen> which should give the Cygwin - <command>kill</command> version number and copyright information. </para> - - <para>Unless you specific the <literal>-f</literal> option, the "pid" - values used by <command>kill</command> are the Cygwin pids, not the - Windows pids. To get a list of running programs and their Cygwin pids, - use the Cygwin <command>ps</command> program. <command>ps -W</command> - will display <emphasis>all</emphasis> windows pids.</para> - - <para>The <command>kill -l</command> option prints the name of the given - signal, or a list of all signal names if no signal is given.</para> - - <para>To send a specific signal, use the <literal>-signN</literal> option, - either with a signal number or a signal name (minus the "SIG" part), as - shown in these examples:</para> - - <example id="utils-kill-ex"> - <title>Using the kill command</title> - <screen> -<prompt>$</prompt> <userinput>kill 123</userinput> -<prompt>$</prompt> <userinput>kill -1 123</userinput> -<prompt>$</prompt> <userinput>kill -HUP 123</userinput> -<prompt>$</prompt> <userinput>kill -f 123</userinput> -</screen> - </example> - - <para>Here is a list of available signals, their numbers, and some - commentary on them, from the file - <literal><sys/signal.h></literal>, which should be considered the - official source of this information.</para> - - <screen> -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 -</screen> - - </sect2> - - <sect2 id="ldd"> - <title>ldd</title> - - <screen> -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) -</screen> - - <para><command>ldd</command> prints the shared libraries (DLLs) an - executable or DLL is linked against. No modifying option is implemented - yet.</para> - - </sect2> - - <sect2 id="locale"> - <title>locale</title> - - <screen> -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 -</screen> - - <para><command>locale</command> without parameters prints information about - the current locale environment settings.</para> - - <para>The <literal>-u</literal>, <literal>-s</literal>, - <literal>-f</literal>, and <literal>-n</literal> 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.</para> - - <para>The <literal>-u</literal> 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 <literal>-s</literal> option prints the systems default - instead. The <literal>-f</literal> 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 <literal>-U</literal> - option <command>locale</command> appends a ".UTF-8".</para> - - <para>Usage example:</para> - - <screen> -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 -</screen> - - <para>The <literal>-a</literal> option is helpful to learn which locales - are supported by your Windows machine. It prints all available locales - and the allowed modifiers. Example:</para> - - <screen> -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 -... -</screen> - - <para>The <literal>-v</literal> option prints more detailed information - about each available locale. Example:</para> - - <screen> -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 - -... -</screen> - - <para>The <literal>-m</literal> option prints the names of the available - charmaps supported by Cygwin to stdout.</para> - - <para>Otherwise, if arguments are given, <command>locale</command> 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 <literal>-c</literal> option prints additionally the name - of the category. The <literal>-k</literal> option prints additionally the - name of the keyword. Example:</para> - - <screen> -bash$ locale -ck LC_MESSAGES -LC_MESSAGES -yesexpr="^[yY]" -noexpr="^[nN]" -yesstr="yes" -nostr="no" -messages-codeset="UTF-8" -bash$ locale noexpr -^[nN] -</screen> - - </sect2> - - <sect2 id="minidumper"><title>minidumper</title> - - <screen> -Usage: minidumper [OPTION] FILENAME WIN32PID - -Write minidump from WIN32PID to FILENAME.dmp - --t, --type minidump type flags --n, --nokill don't terminate the dumped process --d, --verbose be verbose while dumping --h, --help output help information and exit --q, --quiet be quiet while dumping (default) --V, --version output version information and exit - </screen> - - <para> - The <command>minidumper</command> utility can be used to create a - minidump of a running Windows process. This minidump can be later - analysed using breakpad or Windows debugging tools. - </para> - - <para> - <command>minidumper</command> can be used with cygwin's Just-In-Time - debugging facility in exactly the same way as <command>dumper</command> - (See <xref linkend="dumper"></xref>). - </para> - - <para> - <command>minidumper</command> can also be started from the command line to - create a minidump of any running process. For compatibility with - <command>dumper</command> the target process is terminated after dumping - unless the <literal>-n</literal> option is given. - </para> - - </sect2> - - <sect2 id="mkgroup"> - <title>mkgroup</title> - - <screen> -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. -</screen> - - <para>The <command>mkgroup</command> program can be used to help configure - Cygwin by creating a <filename>/etc/group</filename> file. Its use is - essential to include Windows security information.</para> - - <para>The command is initially called by <command>setup.exe</command> to - create a default <filename>/etc/group</filename>. This should be - sufficient in most circumstances. However, especially when working in a - multi-domain environment, you can use <command>mkgroup</command> manually - to create a more complete <filename>/etc/group</filename> file for all - domains. Especially when you have the same group name used on multiple - machines or in multiple domains, you can use the <literal>-D</literal>, - <literal>-L</literal> and <literal>-C</literal> options to create unique - domain\group style groupnames.</para> - - <para>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.</para> - - <para>The <literal>-d/-D</literal> and <literal>-l/-L</literal> options - allow you to specify where the information comes from, the local SAM of a - machine or from the domain, or both. With the <literal>-d/-D</literal> - 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 <command>mkgroup</command>. For very - simple needs, an entry for the current user's group can be created by - using the option <literal>-c</literal> or <literal>-C</literal>. If you - want to use one of the <literal>-D</literal>, <literal>-L</literal> or - <literal>-C</literal> options, but you don't like the backslash as - domain/group separator, you can specify another separator using the - <literal>-S</literal> option, for instance:</para> - - <example id="utils-mkgroup-ex"> - <title>Setting up group entry for current user with different - domain/group separator</title> - <screen> -<prompt>$</prompt> <userinput>mkgroup -C -S+ > /etc/group</userinput> -<prompt>$</prompt> <userinput>cat /etc/group</userinput> -DOMAIN+my_group:S-1-5-21-2913048732-1697188782-3448811101-1144:11144: -</screen> - </example> - - <para>The <literal>-o</literal> option allows for special cases (such as - multiple domains) where the GIDs might match otherwise. The - <literal>-g</literal> option only prints the information for one group. - The <literal>-U</literal> option allows you to enumerate the standard - UNIX groups on a Samba machine. It's used together with <literal>-l - samba-server</literal> or <literal>-L samba-server</literal>. The normal - UNIX groups are usually not enumerated, but they can show up as a group - in <command>ls -l</command> output. </para> - - </sect2> - - <sect2 id="mkpasswd"> - <title>mkpasswd</title> - - <screen> -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. -</screen> - - <para>The <command>mkpasswd</command> program can be used to help configure - Cygwin by creating a <filename>/etc/passwd</filename> 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 <filename>/etc/passwd</filename>.</para> - - <para>The command is initially called by <command>setup.exe</command> to - create a default <filename>/etc/passwd</filename>. This should be - sufficient in most circumstances. However, especially when working in a - multi-domain environment, you can use <command>mkpasswd</command> - manually to create a more complete <filename>/etc/passwd</filename> file - for all domains. Especially when you have the same user name used on - multiple machines or in multiple domains, you can use the - <literal>-D</literal>, <literal>-L</literal> and <literal>-C</literal> - options to create unique domain\user style usernames.</para> - - <para>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.</para> - - <para>The <literal>-d/-D</literal> and <literal>-l/-L</literal> options - allow you to specify where the information comes from, the local machine - or the domain (default or given), or both. With the - <literal>-d/-D</literal> 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 - <command>mkpasswd</command>. An entry for the current user can be created - by using the option <literal>-c</literal> or <literal>-C</literal>. If - you want to use one of the <literal>-D</literal>, <literal>-L</literal> - or <literal>-C</literal> options, but you don't like the backslash as - domain/group separator, you can specify another separator using the - <literal>-S</literal> option, similar to the <command>mkgroup</command>. - The <literal>-o</literal> option allows for special cases (such as - multiple domains) where the UIDs might match otherwise. The - <literal>-p</literal> option causes <command>mkpasswd</command> to use - the specified prefix instead of the account home dir or <literal>/home/ - </literal>. For example, this command: <example id="utils-althome-ex" - ><title>Using an alternate home root</title> - <screen> -<prompt>$</prompt> <userinput>mkpasswd -l -p "$(cygpath -H)" > /etc/passwd</userinput> -</screen> - </example> would put local users' home directories in the Windows - 'Profiles' directory. The <literal>-u</literal> option creates just an - entry for the specified user. The <literal>-U</literal> option allows you - to enumerate the standard UNIX users on a Samba machine. It's used - together with <literal>-l samba-server</literal> or <literal>-L - samba-server</literal>. The normal UNIX users are usually not enumerated, - but they can show up as file owners in <command>ls -l</command> output. </para> - - </sect2> - - <sect2 id="mount"> - <title>mount</title> - - <screen> -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 -</screen> - - <para>The <command>mount</command> 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 <filename>/etc/fstab</filename>, mount points created or - changed with <command>mount</command> are not persistent. They disappear - immediately after the last process of the current user exited. Please see - <xref linkend="mount-table"/> for more information on the concepts behind - the Cygwin POSIX file system and strategies for using mounts. To remove - mounts temporarily, use <command>umount</command></para> - - <sect3 id="utils-mount"> - <title>Using mount</title> - - <para>If you just type <command>mount</command> with no parameters, it - will display the current mount table for you.</para> - - <example id="utils-mount-ex"> - <title>Displaying the current set of mount points</title> - <screen> -<prompt>$</prompt> <userinput>mount</userinput> -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) -</screen> - </example> - - <para>In this example, c:/cygwin is the POSIX root and the D drive is - mapped to <filename>/mnt/d</filename>. 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 <filename>/mnt/d</filename> mount is only - visible to the current user.</para> - - <para>The <command>mount</command> utility is also the mechanism for - adding new mounts to the mount table in memory. The following example - demonstrates how to mount the directory - <filename>//pollux/home/joe/data</filename> to - <filename>/data</filename> for the duration of the current session. </para> - - <example id="utils-mount-add-ex"> - <title>Adding mount points</title> - <screen> -<prompt>$</prompt> <userinput>ls /data</userinput> -ls: /data: No such file or directory -<prompt>$</prompt> <userinput>mount //pollux/home/joe/data /data</userinput> -mount: warning - /data does not exist! -<prompt>$</prompt> <userinput>mount</userinput> -//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) -</screen> - </example> - - <para>A given POSIX path may only exist once in the mount table. Attempts - to replace the mount will fail with a busy error. The - <literal>-f</literal> (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 <literal>-f</literal> option will silence warnings - about the non-existence of directories at the Win32 path - location.</para> - - <para> The <literal>-o</literal> 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):</para> - - <screen> - 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. -</screen> - - <para>For a more complete description of the mount options and the - <filename>/etc/fstab</filename> file, see <xref linkend="mount-table" - />.</para> - - <para>Note that all mount points added with <command>mount</command> are - user mount points. System mount points can only be specified in the - <filename>/etc/fstab</filename> file.</para> - - <para>If you added mount points to <filename>/etc/fstab</filename> or - your <filename>/etc/fstab.d/<username></filename> file, you can - add these mount points to your current user session using the - <literal>-a/--all</literal> 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 <filename>/my/mount</filename>. You can add - this mount point with either one of the following two commands to your - current user session.</para> - - <screen> -<prompt>$</prompt> <userinput>mount /my/mount</userinput> -<prompt>$</prompt> <userinput>mount -a</userinput> -</screen> - - <para>The first command just adds the <filename>/my/mount</filename> - mount point to your current session, the <command>mount -a</command> - adds all new mount points to your user session.</para> - - <para>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 - <command>umount</command> 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.</para> - - <para>To bind a POSIX path to another POSIX path, use the - <literal>bind</literal> mount flag.</para> - - <screen> -<prompt>$</prompt> <userinput>mount -o bind /var /usr/var</userinput> -</screen> - - <para>This command makes the file hirarchy under - <filename>/var</filename> additionally available under - <filename>/usr/var</filename>.</para> - - <para> The <literal>-m</literal> option causes the - <command>mount</command> 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 - <filename>/etc/fstab</filename> to restore the old state. It also makes - moving your settings to a different machine much easier.</para> - - </sect3> - - <sect3 id="utils-cygdrive"> - <title>Cygdrive mount points</title> - - <para>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: - <filename>/cygdrive</filename>. For example, if Cygwin accesses - <filename>z:\foo</filename> and the z drive is not currently in the - mount table, then <filename>z:\</filename> will be accessible as - <filename>/cygdrive/z</filename>. The <command>mount</command> 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 <filename>/mnt</filename>:</para> - - <example id="utils-cygdrive-ex"> - <title>Changing the default prefix</title> - <screen> -<prompt>$</prompt> <userinput>mount --change-cygdrive-prefix /mnt</userinput> -</screen> - </example> - - <para>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 <command>mount</command> - 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 - <literal>-p</literal> option. Using the <literal>--options</literal> - flag with <literal>--change-cygdrive-prefix</literal> makes all new - automounted filesystems default to this set of options. For instance - (using the short form of the command line flags)</para> - - <example id="utils-cygdrive-ex2"> - <title>Changing the default prefix with specific mount options</title> - <screen> -<prompt>$</prompt> <userinput>mount -c /mnt -o binary,noacl</userinput> -</screen> - </example> - - - </sect3> - - <sect3 id="utils-limitations"> - <title>Limitations</title> - - <para>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.</para> - - <para>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. </para> - - <para>It is sometimes desirable to mount to a non-existent directory, for - example to avoid cluttering the root directory with names such as - <filename>a</filename>, <filename>b</filename>, <filename>c</filename> - pointing to disks. Although <command>mount</command> 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 <filename>/dir</filename>, say, - and <filename>/dir/mtpt</filename> is a mount point, then - <filename>mtpt</filename> will not show up in an <command>ls</command> - or <command>echo *</command> command and <command>find .</command> will - not find <filename>mtpt</filename>. </para> - - </sect3> - - </sect2> - - <sect2 id="passwd"> - <title>passwd</title> - - <screen> -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. -</screen> - - <para> <command>passwd</command> 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. - <command>passwd</command> also changes account information, such as - password expiry dates and intervals.</para> - - <para>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.</para> - - <para>The user is then prompted for a replacement password. - <command>passwd</command> 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.</para> - - <para>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, <command>passwd</command> refuses to change the password - and exits.</para> - - <para> To get current password status information, use the - <literal>-S</literal> option. Administrators can use - <command>passwd</command> to perform several account maintenance - functions (users may perform some of these functions on their own - accounts). Accounts may be locked with the <literal>-l</literal> flag and - unlocked with the <literal>-u</literal> flag. Similarly, - <literal>-c</literal> disables a user's ability to change passwords, and - <literal>-C</literal> allows a user to change passwords. For password - expiry, the <literal>-e</literal> option disables expiration, while the - <literal>-E</literal> option causes the password to expire according to - the system's normal aging rules. Use <literal>-p</literal> to disable the - password requirement for a user, or <literal>-P</literal> to require a - password. </para> - - <para>Administrators can also use <command>passwd</command> to change - system-wide password expiry and length requirements with the - <literal>-i</literal>, <literal>-n</literal>, <literal>-x</literal>, and - <literal>-L</literal> options. The <literal>-i</literal> 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 - <emphasis>NUM</emphasis> days, the user may no longer sign on to the - account. The <literal>-n</literal> 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 <emphasis>MINDAYS</emphasis> days - have elapsed. The <literal>-x</literal> option is used to set the maximum - number of days a password remains valid. After - <emphasis>MAXDAYS</emphasis> days, the password is required to be - changed. Allowed values for the above options are 0 to 999. The - <literal>-L</literal> option sets the minimum length of allowed passwords - for users who don't belong to the administrators group to - <emphasis>LEN</emphasis> 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'.</para> - - <para> All operations affecting the current user are by default run against - the logon server of the current user (taken from the environment variable - <envar>LOGONSERVER</envar>. 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 <literal>-d</literal> - 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. </para> - - <para>Users can use the <command>passwd -R</command> 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 - <command>set{e}uid(user_id)</command> 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, <command>ssh</command> - 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 <xref - linkend="ntsec"/>.</para> - - <para>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 - <command>passwd -R</command>, it's required to run - <command>cygserver</command> as a service under the LocalSystem account - before running <command>passwd -R</command>. This only affects storing - passwords. Using passwords in privileged processes does not require - <command>cygserver</command> to run.</para> - - <para>Limitations: Users may not be able to change their password on some - systems.</para> - - </sect2> - - <sect2 id="pldd"> - <title>pldd</title> - - <screen> -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 -</screen> - - <para><command>pldd</command> prints the shared libraries (DLLs) loaded by - the process with the given PID.</para> - - </sect2> - - <sect2 id="ps"> - <title>ps</title> - - <screen> -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 -</screen> - - <para>The <command>ps</command> 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. </para> - - <para> The PID column is the process ID you need to give to the - <command>kill</command> 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 <literal>'?'</literal> 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; - <literal>S</literal> means stopped or suspended (in other words, in the - background), <literal>I</literal> means waiting for input or interactive - (foreground), and <literal>O</literal> means waiting to output. </para> - - <para> By default, <command>ps</command> will only show processes owned by - the current user. With either the <literal>-a</literal> or - <literal>-e</literal> option, all user's processes (and system processes) - are listed. There are historical UNIX reasons for the synonomous options, - which are functionally identical. The <literal>-f</literal> option - outputs a "full" listing with usernames for UIDs. The - <literal>-l</literal> option is the default display mode, showing a - "long" listing with all the above columns. The other display option is - <literal>-s</literal>, which outputs a shorter listing of just PID, TTY, - STIME, and COMMAND. The <literal>-u</literal> option allows you to show - only processes owned by a specific user. The <literal>-p</literal> option - allows you to show information for only the process with the specified - PID. The <literal>-W</literal> option causes <command>ps</command> show - non-Cygwin Windows processes as well as Cygwin processes. The WINPID is - also the PID, and they can be killed with the Cygwin - <command>kill</command> command's <literal>-f</literal> option. </para> - - </sect2> - - <sect2 id="regtool"> - <title>regtool</title> - - <screen> -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' -</screen> - - <para>The <command>regtool</command> 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.</para> - - <para>The <literal>-v</literal> option means "verbose". For most commands, - this causes additional or lengthier messages to be printed. Conversely, - the <literal>-q</literal> option supresses error messages, so you can use - the exit status of the program to detect if a key exists or not (for - example).</para> - - <para>The <literal>-w</literal> 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 - <literal>-w</literal> switch, the 64 bit view is used and - <command>regtool</command> can access the entire registry. This option is - simply ignored when running on 32 bit Windows versions. </para> - - <para>The <literal>-W</literal> 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.</para> - - <para>You must provide <command>regtool</command> with an - <emphasis>action</emphasis> following options (if any). Currently, the - action must be <literal>add</literal>, <literal>set</literal>, - <literal>check</literal>, <literal>get</literal>, - <literal>list</literal>, <literal>remove</literal>, - <literal>set</literal>, or <literal>unset</literal>. </para> - - <para>The <literal>add</literal> action adds a new key. The - <literal>check</literal> 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 - <literal>get</literal> 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 <literal>-q</literal>, it doesn't print the message but does return - the non-zero exit code.</para> - - <para> The <literal>list</literal> action lists the subkeys and values - belonging to the given key. With <literal>list</literal>, the - <literal>-k</literal> option instructs <command>regtool</command> to - print only KEYs, and the <literal>-l</literal> option to print only - VALUEs. The <literal>-p</literal> option postfixes a - <literal>'/'</literal> to each KEY, but leave VALUEs with no postfix. The - <literal>remove</literal> 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. </para> - - <para>The <literal>get</literal> action prints a value within a key. With - the <literal>-b</literal> option, data is printed as hex bytes. - <literal>-n</literal> allows to print the data as a typeless stream of - bytes. Integer values (REG_DWORD, REG_QWORD) are usually printed as - decimal values. The <literal>-x</literal> option allows to print the - numbers as hexadecimal values.</para> - - <para>The <literal>set</literal> action sets a value within a key. - <literal>-b</literal> means it's binary data (REG_BINARY). The binary - values are specified as hex bytes in the argument list. If the argument - is <literal>'-'</literal>, binary data is read from stdin instead. - <literal>-d</literal> or <literal>-i</literal> means the value is a 32 - bit integer value (REG_DWORD). <literal>-D</literal> means the value is a - 32 bit integer value in Big Endian representation (REG_DWORD_BIG_ENDIAN). - <literal>-Q</literal> means the value is a 64 bit integer value - (REG_QWORD). <literal>-s</literal> means the value is a string (REG_SZ). - <literal>-e</literal> means it's an expanding string (REG_EXPAND_SZ) that - contains embedded environment variables. <literal>-m</literal> means it's - a multi-string (REG_MULTI_SZ). If you don't specify one of these, - <command>regtool</command> 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.</para> - - <para>The <literal>unset</literal> action removes a value from a - key.</para> - - <para>The <literal>load</literal> 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 <literal>unload</literal> action - unloads the file and removes the subkey. </para> - - <para>The <literal>save</literal> action saves a subkey into a registry - hive. </para> - - <para> By default, the last "\" or "/" is assumed to be the separator - between the key and the value. You can use the <literal>-K</literal> - option to provide an alternate key/value separator character. </para> - - </sect2> - - <sect2 id="setfacl"> - <title>setfacl</title> - - <screen> -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 -</screen> - - <para> For each file given as parameter, <command>setfacl</command> will - either replace its complete ACL (<literal>-s</literal>, - <literal>-f</literal>), or it will add, modify, or delete ACL entries. - For more information on Cygwin and Windows ACLs, see see <xref - linkend="ntsec"/> in the Cygwin User's Guide. </para> - - <para> Acl_entries are one or more comma-separated ACL entries from the - following list: - <screen> - u[ser]::perm - u[ser]:uid:perm - g[roup]::perm - g[roup]:gid:perm - m[ask]::perm - o[ther]::perm -</screen> - Default entries are like the above with the additional default - identifier. For example: - <screen> - d[efault]:u[ser]:uid:perm -</screen> </para> - - <para> <emphasis>perm</emphasis> is either a 3-char permissions string in - the form "rwx" with the character <literal>'-'</literal> for no - permission or it is the octal representation of the permissions, a value - from 0 (equivalent to "---") to 7 ("rwx"). <emphasis>uid</emphasis> is a - user name or a numerical uid. <emphasis>gid</emphasis> is a group name or - a numerical gid. </para> - - <para> The following options are supported: </para> - - <para> <literal>-d</literal> 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: - <screen> - u[ser]:uid - g[roup]:gid - d[efault]:u[ser]:uid - d[efault]:g[roup]:gid - d[efault]:m[ask]: - d[efault]:o[ther]: -</screen> </para> - - <para> <literal>-f</literal> 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 <command>getfacl</command> and - <command>setfacl</command> to copy ACLs from one file to another: - <screen> -$ getfacl source_file | setfacl -f - target_file -</screen> </para> - - <para> 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. </para> - - <para> 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. </para> - - <para> 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. </para> - - <para> <literal>-m</literal> Add or modify one or more specified ACL - entries. Acl_entries is a comma-separated list of entries from the same - list as above. </para> - - <para> <literal>-r</literal> Causes the permissions specified in the mask - entry to be ignored and replaced by the maximum permissions needed for - the file group class. </para> - - <para> <literal>-s</literal> Like <literal>-f</literal>, but substitute the - file's ACL with Acl_entries specified in a comma-separated list on the - command line. </para> - - <para> While the <literal>-d</literal> and <literal>-m</literal> options - may be used in the same command, the <literal>-f</literal> and - <literal>-s</literal> options may be used only exclusively. </para> - - <para> 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 </para> - - <para> Limitations: Under Cygwin, the default ACL entries are not taken - into account currently. </para> - - </sect2> - - <sect2 id="setmetamode"> - <title>setmetamode</title> - - <screen> -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 -</screen> - - <para><command>setmetamode</command> can be used to determine and set the - key code sent by the meta (aka <literal>Alt</literal>) key.</para> - - </sect2> - - <sect2 id="ssp"> - <title>ssp</title> - - <screen> -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 -</screen> - - <para> SSP - The Single Step Profiler </para> - - <para> Original Author: DJ Delorie </para> - - <para> 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 <command>gprof</command>, although - <command>gprof</command> will claim the values are seconds, they really - are instruction counts. More on that later. </para> - - <para> 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 <command>gprof</command> won't run) and run objdump like - this: <screen> -$ objdump -h cygwin1.dll -</screen> It will print a report - like this: - <screen> -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 - . . . -</screen> </para> - - <para> 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). </para> - - <para> There are two basic ways to use SSP - either profiling a whole - program, or selectively profiling parts of the program. </para> - - <para> To profile a whole program, just run <command>ssp</command> without - options. By default, it will step the whole program. Here's a simple - example, using the numbers above: - <screen> -$ ssp 0x61001000 0x61080000 hello.exe -</screen> 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 <command>gprof</command>: - <screen> -$ gprof -b cygwin1.dll -</screen> The "-b" means 'skip the help - pages'. You can omit this until you're familiar with the report layout. - The <command>gprof</command> documentation explains a lot about this - report, but <command>ssp</command> changes a few things. For example, the - first part of the report reports the amount of time spent in each - function, like this: - <screen> -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 -</screen> - 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. </para> - - <para> 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: - <screen> - #include <windows.h> - main() - { - time_t t; - OutputDebugString("ssp on"); - time(&t); - OutputDebugString("ssp off"); - } -</screen> </para> - - <para> Then, add the <literal>-d</literal> 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 - <command>gprof</command> (as usual) to see the performance profile for - just that portion of the program's execution. </para> - - <para> 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. </para> - - <para> <literal>-v</literal> - verbose. This prints messages about threads - starting and stopping, OutputDebugString calls, DLLs loading, etc. </para> - - <para> <literal>-t</literal> and <literal>-c</literal> - tracing. With - <literal>-t</literal>, *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. <literal>-c</literal> prints each address to the console, useful - for debugging key chunks of assembler. Use <literal>addr2line -C -f -s -e - foo.exe < trace.ssp > lines.ssp</literal> and then <literal>perl - cvttrace</literal> to convert to symbolic traces. </para> - - <para> <literal>-s</literal> - 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. </para> - - <para> <literal>-l</literal> - 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 <literal>-v</literal>, <literal>-s</literal>, and - <literal>-l</literal> options: - <screen> -$ ssp <literal>-v</literal> <literal>-s</literal> <literal>-l</literal> <literal>-d</literal> 0x61001000 0x61080000 hello.exe -</screen> - </para> - </sect2> - - <sect2 id="strace"> - <title>strace</title> - - <screen> -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 -</screen> - - <para>The <command>strace</command> 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 - <literal>-o</literal> option. With the <literal>-w</literal> option, you - can start an strace session in a new window, for example: - <screen> -$ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' & -</screen> - This is particularly useful for <command>strace</command> sessions that - take a long time to complete. </para> - - <para> Note that <command>strace</command> is a standalone Windows program - and so does not rely on the Cygwin DLL itself (you can verify this with - <command>cygcheck</command>). As a result it does not understand - symlinks. This program is mainly useful for debugging the Cygwin DLL - itself.</para> - - </sect2> - - <sect2 id="tzset"> - <title>tzset</title> - - <screen> -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` -</screen> - - <para>The <command>tzset</command> 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.</para> - - </sect2> - - <sect2 id="umount"> - <title>umount</title> - - <screen> -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 -</screen> - - <para>The <command>umount</command> program removes mounts from the mount - table in the current session. If you specify a POSIX path that - corresponds to a current mount point, <command>umount</command> will - remove it from the current mount table. Note that you can only remove - user mount points. The <literal>-U</literal> flag may be used to specify - removing all user mount points from the current user session.</para> - - <para>See <xref linkend="mount-table"/> for more information on the mount - table.</para> - </sect2> - -</sect1> |