utils.sgml

cygwin, 著名的在win32下模拟unix操作系统的东东

<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&gt;</prompt> <userinput>cygcheck -s -v -r -h &gt; 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>&lt;sys/signal.h&gt;</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