1371 lines
56 KiB
Plaintext
1371 lines
56 KiB
Plaintext
<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 ...]
|
|
-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]
|
|
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]
|
|
-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]
|
|
|
|
This program prints a /etc/group file to stdout
|
|
|
|
Options:
|
|
-l,--local print local group information
|
|
-d,--domain print global group information from the domain
|
|
specified (or from the current domain if there is
|
|
no domain specified)
|
|
-o,--id-offset offset change the default offset (10000) added to uids
|
|
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> substitute (some commands need this
|
|
file) from your system information. It only works on the NT series
|
|
(Windows NT, 2000, and XP). <command>mkgroup</command> does not work on
|
|
the Win9x series (Windows 95, 98, and Me) because they lack the security model
|
|
to support it. To initially set up your machine, you'd do something like
|
|
this:</para>
|
|
|
|
<example><title>Setting up the groups file</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, either the
|
|
local machine or the default (or given) domain. 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.
|
|
</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2 id="mkpasswd"><title>mkpasswd</title>
|
|
|
|
<screen>
|
|
Usage: mkpasswd [OPTION]... [domain]
|
|
|
|
This program prints a /etc/passwd file to stdout
|
|
|
|
Options:
|
|
-l,--local print local user accounts
|
|
-d,--domain print domain accounts (from current domain
|
|
if no domain 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 domain 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 instead of user account home dir
|
|
-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> substitute (some commands
|
|
need this file) from your system information. It only works on the NT series
|
|
(Windows NT, 2000, and XP). <command>mkpasswd</command> does not work on
|
|
the Win9x series (Windows 95, 98, and Me) because they lack the security model
|
|
to support it. To initially set up your machine, you'd do something like
|
|
this:</para>
|
|
|
|
<example><title>Setting up the passwd file</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, either the
|
|
local machine or the default (or given) domain. 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 a prefix other than <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.
|
|
The <literal>-u</literal> option allows <command>mkpasswd</command> to
|
|
search for a specific username, 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>]
|
|
-b, --binary 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
|
|
-p, --show-cygdrive-prefix show user and/or system cygdrive path prefix
|
|
-s, --system (default) add system-wide mount point
|
|
-t, --text (default) 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>
|
|
|
|
</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 you 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 current user.
|
|
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]
|
|
|
|
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]
|
|
-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
|
|
|
|
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
|
|
|
|
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>
|
|
|
|
</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...
|
|
-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>
|
|
-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>]
|
|
-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>
|