diff options
Diffstat (limited to 'winsup/utils/utils.sgml')
-rw-r--r-- | winsup/utils/utils.sgml | 1433 |
1 files changed, 0 insertions, 1433 deletions
diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml deleted file mode 100644 index ec80be8..0000000 --- a/winsup/utils/utils.sgml +++ /dev/null @@ -1,1433 +0,0 @@ -<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 [OPTIONS] [program ...] -Check system information or PROGRAM library dependencies - - -c, --check-setup check packages installed via setup.exe - -s, --sysinfo system information (not with -k) - -v, --verbose verbose output (indented) (for -s or programs) - -r, --registry registry search (requires -s) - -k, --keycheck perform a keyboard check session (not with -s) - -h, --help give help about the info (not with -c) - -V, --version output version information and exit -You must at least give either -s or -k or a program name -</screen> - -<para>The <command>cygcheck</command> program is a diagnostic utility -that examines your system and reports the information that is -significant to the proper operation of Cygwin programs. It can give -information about specific programs or libraries you are trying to -run, general system information, or both. If you list one or more -programs on the command line, it 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, it will give general system information. If you specify -<literal>-s</literal> and list one or more programs on the command line, -it reports on both.</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 relevent 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>The <literal>-c</literal> option causes the arguments -to be interpreted as package names. <command>cygcheck</command> will -report the current version of the package that you specify, or with no -arguments, on all packages.</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>C:\cygwin></prompt> <userinput>cygcheck -s -v -r -h > cygcheck_output.txt</userinput> -</screen> - -</sect2> - -<sect2 id="cygpath"><title>cygpath</title> - -<screen> -Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-c HANDLE] [-f FILE] [options] NAME - cygpath [-ADHPSW] -Convert Unix and Windows format paths, or output system path information - -Output type options: - -d, --dos print DOS (short) form of NAME (C:\PROGRA~1\) - -m, --mixed like --windows, but with regular slashes (C:/WINNT) - -u, --unix (default) print Unix form of NAME (/cygdrive/c/winnt) - -w, --windows print Windows form of NAME (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 NAME (with -w, -m only) - -p, --path NAME is a PATH list (i.e., '/bin:/usr/bin') - -s, --short-name print DOS (short) form of NAME (with -w, -m only) -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 - -P, --smprograms output Start Menu `Programs' directory and exit - -S, --sysdir output system directory and exit - -W, --windir output `Windows' directory 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>Caveat: The <literal>-l</literal> option does not work if the -<emphasis>check_case</emphasis> parameter of <emphasis>CYGWIN</emphasis> -is set to <emphasis>strict</emphasis>, since Cygwin is not able to match -any Windows short path in this mode. -</para> - -<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><title>Example cygpath usage</title> -<screen> -#!/bin/sh -if [ "${1}" = "" ]; - then - XPATH="."; - else - XPATH="$(cygpath -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\SYSTEM. -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> and <literal>-P</literal> options. -On Win9x systems with only a single user, <literal>-A</literal> has no -effect; <literal>-D</literal> and <literal>-AD</literal> would have the -same output. 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="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 -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), like these examples:</para> - -<example><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 -SIGTTIN 21 to readers pgrp upon background tty read -SIGTTOU 22 like TTIN for output if (tp->t_local&LTOSTOP) -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) -SIGUSR1 30 user defined signal 1 -SIGUSR2 31 user defined signal 2 -</screen> - -</sect2> - -<sect2 id="mkgroup"><title>mkgroup</title> - -<screen> -Usage: mkgroup [OPTION]... [domain]... -Prints /etc/group file to stdout - -Options: - -l,--local print local group information - -c,--current print current group, if a domain account - -d,--domain print global group information (from current - domain if no domains specified). - -o,--id-offset offset change the default offset (10000) added to gids - in domain accounts. - -s,--no-sids don't print SIDs in pwd field - (this affects ntsec) - -u,--users print user list in gr_mem field - -h,--help print this message - - -v,--version print version information and exit - -One of `-l' or `-d' must be given on NT/W2K. -</screen> - -<para>The <command>mkgroup</command> program can be used to help -configure your Windows system to be more UNIX-like by creating an -initial <filename>/etc/group</filename>. -Its use is essential on the NT series (Windows NT, 2000, and XP) to -include Windows security information. -It can also be used on the Win9x series (Windows 95, 98, and Me) to -create a file with the correct format. -To initially set up your machine if you are a local user, you'd do -something like this:</para> - -<example><title>Setting up the groups file for local accounts</title> -<screen> -<prompt>$</prompt> <userinput>mkdir /etc</userinput> -<prompt>$</prompt> <userinput>mkgroup -l > /etc/group</userinput> -</screen> -</example> - -<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</literal> and <literal>-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</literal> option the program contacts the Domain -Controller, which my be unreachable or have restricted access. -An entry for the current domain user can then be created by using the -option <literal>-c</literal> together with <literal>-l</literal>, -but <literal>-c</literal> has no effect when used with <literal>-d</literal>. -The <literal>-o</literal> option allows for special cases -(such as multiple domains) where the GIDs might match otherwise. -The <literal>-s</literal> -option omits the NT Security Identifier (SID). For more information on -SIDs, see <Xref Linkend="ntsec"> in the Cygwin User's Guide. The -<literal>-u</literal> option causes <command>mkgroup</command> to -enumerate the users for each group, placing the group members in the -gr_mem (last) field. Note that this can greatly increase -the time for <command>mkgroup</command> to run in a large domain. -Having gr_mem fields is helpful when a domain user logs in remotely -while the local machine is disconnected from the Domain Controller. -</para> - -</sect2> - -<sect2 id="mkpasswd"><title>mkpasswd</title> - -<screen> -Usage: mkpasswd [OPTION]... [domain]... -Prints /etc/passwd file to stdout - -Options: - -l,--local print local user accounts - -c,--current print current account, if a domain account - -d,--domain print domain accounts (from current domain - if no domains specified) - -o,--id-offset offset change the default offset (10000) added to uids - in domain accounts. - -g,--local-groups print local group information too - if no domains specified - -m,--no-mount don't use mount points for home dir - -s,--no-sids don't print SIDs in GCOS field - (this affects ntsec) - -p,--path-to-home path use specified path and not user account home dir or /home - -u,--username username only return information for the specified user - -h,--help displays this message - -v,--version version information and exit - -One of `-l', `-d' or `-g' must be given on NT/W2K. -</screen> - -<para>The <command>mkpasswd</command> program can be used to help -configure your Windows system to be more UNIX-like by creating an -initial <filename>/etc/passwd</filename> from your system information. -Its use is essential on the NT series (Windows NT, 2000, and XP) to -include Windows security information, but the actual passwords are -determined by Windows, not by the content of <filename>/etc/passwd</filename>. -On the Win9x series (Windows 95, 98, and Me) the password field must be -replaced by the output of <userinput>crypt your_password</userinput> -if remote access is desired. -To initially set up your machine if you are a local user, you'd do -something like this:</para> - -<example><title>Setting up the passwd file for local accounts</title> -<screen> -<prompt>$</prompt> <userinput>mkdir /etc</userinput> -<prompt>$</prompt> <userinput>mkpasswd -l > /etc/passwd</userinput> -</screen> -</example> - -<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</literal> and <literal>-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</literal> option the program contacts the Domain -Controller, which my be unreachable or have restricted access. -An entry for the current domain user can then be created by using the -option <literal>-c</literal> together with <literal>-l</literal>, -but <literal>-c</literal> has no effect when used with <literal>-d</literal>. -The <literal>-o</literal> option allows for special cases -(such as multiple domains) where the UIDs might match otherwise. -The <literal>-g</literal> option creates a local -user that corresponds to each local group. This is because NT assigns groups -file ownership. The <literal>-m</literal> option bypasses the current -mount table so that, for example, two users who have a Windows home -directory of H: could mount them differently. The <literal>-s</literal> -option omits the NT Security Identifier (SID). For more information on -SIDs, see <Xref Linkend="ntsec"> in the Cygwin User's Guide. 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><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. -On Win9x machines the <literal>-u</literal> option creates an entry for -the specified user. On the NT series it restricts the output to that user, -greatly reducing the amount of time it takes in a large domain.</para> - -</sect2> - -<sect2 id="mount"><title>mount</title> - -<screen> -Usage: mount [OPTION] [<win32path> <posixpath>] -Display information about mounted filesystems, or mount a filesystem - - -b, --binary (default) text files are equivalent to binary files - (newline = \n) - -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-commands write mount commands to replace user and - system mount points and cygdrive prefixes - -o, --options X[,X...] specify mount options - -p, --show-cygdrive-prefix show user and/or system cygdrive path prefix - -s, --system (default) add system-wide mount point - -t, --text text files get \r\n line endings - -u, --user add user-only mount point - -v, --version output version information and exit - -x, --executable treat all files under mount point as executables - -E, --no-executable treat all files under mount point as - non-executables - -X, --cygwin-executable treat all files under mount point as cygwin - executables -</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. 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, use <command>umount</command></para> - -<sect3><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> -<title>Displaying the current set of mount points</title> -<screen> -<prompt>c:\cygwin\></prompt> <userinput>mount</userinput> -c:\cygwin\bin on /usr/bin type system (binmode) -c:\cygwin\lib on /usr/lib type system (binmode) -c:\cygwin on / type system (binmode) -c: on /c type user (binmode,noumount) -d: on /d type user (binmode,noumount) -</screen> -</example> - -<para>In this example, c:\cygwin is the POSIX root and D drive is mapped to -<filename>/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>/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. The following example -demonstrates how to mount the directory -<filename>\\pollux\home\joe\data</filename> to <filename>/data</filename>. -</para> - -<example> -<title>Adding mount points</title> -<screen> -<prompt>c:\cygwin\></prompt> <userinput>ls /data</userinput> -ls: /data: No such file or directory -<prompt>c:\cygwin\></prompt> <userinput>mount \\pollux\home\joe\data /data</userinput> -mount: warning - /data does not exist! -<prompt>c:\cygwin\></prompt> <userinput>mount</userinput> -\\pollux\home\joe\data on /data type sytem (binmode) -c:\cygwin\bin on /usr/bin type system (binmode) -c:\cygwin\lib on /usr/lib type system (binmode) -c:\cygwin on / type system (binmode) -c: on /c type user (binmode,noumount) -d: on /d type user (binmode,noumount) -</screen> -</example> - -<para>Note that <command>mount</command> was invoked from the Windows -command shell in the previous example. In many Unix shells, including -bash, it is legal and convenient to use the forward "/" in Win32 -pathnames since the "\" is the shell's escape character. </para> - -<para>The <literal>-s</literal> flag to <command>mount</command> is used to add a mount -in the system-wide mount table used by all Cygwin users on the system, -instead of the user-specific one. System-wide mounts are displayed -by <command>mount</command> as being of the "system" type, as is the -case for the <filename>/</filename> partition in the last example. -Under Windows NT, only those users with Administrator priviledges are -permitted to modify the system-wide mount table.</para> - -<para>Note that a given POSIX path may only exist once in the user -table and once in the global, system-wide table. Attempts to replace -the mount will fail with a busy error. The <literal>-f</literal> (force) flag causes -the old mount to be silently replaced with the new one. It will also -silence warnings about the non-existence of directories at the Win32 -path location.</para> - -<para>The <literal>-b</literal> flag is used to instruct Cygwin to treat binary and -text files in the same manner by default. Binary mode mounts are -marked as "binmode" in the Flags column of <command>mount</command> -output. By default, mounts are in text mode ("textmode" in the Flags -column).</para> - -<para>Normally, files ending in certain extensions (.exe, .com, .bat, .cmd) -are assumed to be executable. Files whose first two characters begin with -'#!' are also considered to be executable. -The <literal>-x</literal> flag is used to instruct Cygwin that the -mounted file is "executable". If the <literal>-x</literal> flag is used -with a directory then all files in the directory are executable. -This option allows other files to be marked as executable and avoids the -overhead of opening each file to check for a '#!'. The <literal>-X</literal> -option is very similar to <literal>-x</literal>, but also prevents Cygwin -from setting up commands and environment variables for a normal Windows -program, adding another small performance gain. The opposite of these -flags is the <literal>-E</literal> flag, which means that no files should be -marked as executable. </para> - -<para> -The <literal>-m</literal> option causes the <command>mount</command> utility -to output a series of commands that could recreate both user and system mount -points. You can save this output as a backup when experimenting with the -mount table. It also makes moving your settings to a different machine -much easier. -</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> - user - mount lives user-specific mount - system - mount lives in system table (default) - binary - files default to binary mode (default) - text - files default to CRLF text mode line endings - exec - files below mount point are all executable - notexec - files below mount point are not executable - cygexec - files below mount point are all cygwin executables - nosuid - no suid files are allowed (currently unimplemented) - managed - directory is managed by cygwin. Mixed case and special - characters in filenames are allowed. -</screen> -</sect3> - -<sect3><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>/</filename>:</para> - -<example> -<title>Changing the default prefix</title> -<screen> -<prompt>c:\cygwin\></prompt> <userinput>mount --change-cygdrive-prefix /</userinput> -</screen> -</example> - -<para>Note that if you set a new prefix in this manner, you can -specify the <literal>-s</literal> flag to make this the system-wide default -prefix. By default, the cygdrive-prefix applies only to the system-wide setting. -You can always see the user and system cygdrive prefixes with the -<literal>-p</literal> option. Using the <literal>-b</literal> -flag with <literal>--change-cygdrive-prefix</literal> makes all new -automounted filesystems default to binary mode file accesses.</para> - -</sect3> - -<sect3><title>Limitations</title> - -<para>Limitations: there is a hard-coded limit of 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 (-l|-u|-S) [USER] - passwd [-i NUM] [-n MINDAYS] [-x MAXDAYS] [-L LEN] -Change USER's password or password attributes - -User operations: - -l, --lock lock USER's account - -u, --unlock unlock USER's account - -S, --status display password status for USER (locked, expired, etc.) - -System operations: - -i, --inactive set NUM of days before inactive accounts are disabled - (inactive accounts are those with expired passwords) - -n, --minage set system minimum password age to MINDAYS - -x, --maxage set system maximum password age to MAXDAYS - -L, --length set system minimum password length to LEN - -Other options: - -h, --help output usage information and exit - -v, --version output version information and exit -</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>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 require 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>Account maintenance: User accounts may be locked and unlocked with the -<literal>-l</literal> and <literal>-u</literal> flags. The -<literal>-l</literal> option disables an account. The <literal>-u</literal> -option re-enables an account.</para> - -<para>The account status may be given with the <literal>-S</literal> -option. The status information is self explanatory.</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>Limitations: Users may not be able to change their password on -some systems.</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 - -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. -</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>-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.exe [OPTION] (add | check | get | list | remove | unset) 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 - -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 'set' Action: - -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 - -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 - -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>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 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>set</literal> action sets a value within a key. -<literal>-e</literal> means it's an expanding string (REG_EXPAND_SZ) -that contains embedded environment variables. -<literal>-i</literal> means the value is an integer (REG_DWORD). -<literal>-m</literal> means it's a multi-string (REG_MULTI_SZ). -<literal>-s</literal> means the value is a string (REG_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. If it starts with a percent, it's an expanding -string. If you give multiple values, it's a multi-string. Else, it's -a regular string. -The <literal>unset</literal> action removes a value from a key. -</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="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 - -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> - -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 0x00001 (_STRACE_ALL) All strace messages. - flush 0x00002 (_STRACE_FLUSH) Flush output buffer after each message. - inherit 0x00004 (_STRACE_INHERIT) Children inherit mask from parent. - uhoh 0x00008 (_STRACE_UHOH) Unusual or weird phenomenon. - syscall 0x00010 (_STRACE_SYSCALL) System calls. - startup 0x00020 (_STRACE_STARTUP) argc/envp printout at startup. - debug 0x00040 (_STRACE_DEBUG) Info to help debugging. - paranoid 0x00080 (_STRACE_PARANOID) Paranoid info. - termios 0x00100 (_STRACE_TERMIOS) Info for debugging termios stuff. - select 0x00200 (_STRACE_SELECT) Info on ugly select internals. - wm 0x00400 (_STRACE_WM) Trace Windows msgs (enable _strace_wm). - sigp 0x00800 (_STRACE_SIGP) Trace signal and process handling. - minimal 0x01000 (_STRACE_MINIMAL) Very minimal strace output. - exitdump 0x04000 (_STRACE_EXITDUMP) Dump strace cache on exit. - system 0x08000 (_STRACE_SYSTEM) Serious error; goes to console and log. - nomutex 0x10000 (_STRACE_NOMUTEX) Don't use mutex for synchronization. - malloc 0x20000 (_STRACE_MALLOC) Trace malloc calls. - thread 0x40000 (_STRACE_THREAD) Thread-locking calls. -</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 POSIX -pathnames or symlinks. This program is mainly useful for debugging the -Cygwin DLL itself.</para> - -</sect2> - -<sect2 id="umount"><title>umount</title> - -<screen> -Usage: umount.exe [OPTION] [<posixpath>] -Unmount filesystems - - -A, --remove-all-mounts remove all mounts - -c, --remove-cygdrive-prefix remove cygdrive prefix - -h, --help output usage information and exit - -s, --system remove system mount (default) - -S, --remove-system-mounts remove all system mounts - -u, --user remove user mount - -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. If you specify a POSIX path that corresponds to a -current mount point, <command>umount</command> will remove it from the -system registry area. (Administrator priviledges are required). -The <literal>-u</literal> flag may be used to specify removing the mount -from the user-specific registry area instead.</para> - -<para>The <command>umount</command> utility may also be used to remove -all mounts of a particular type. With the extended options it is -possible to remove all mounts (<literal>-A</literal>), all -cygdrive automatically-mounted mounts (<literal>-c</literal>), all -mounts in the current user's registry area (<literal>-U</literal>), -or all mounts in the system-wide registry area (<literal>-S</literal>) -(with Administrator privileges).</para> - -<para>See <Xref Linkend="mount"> for more information on the mount -table.</para> -</sect2> - -</sect1> |