2493 lines
107 KiB
XML
2493 lines
107 KiB
XML
<?xml version="1.0" encoding='UTF-8'?>
|
|
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
|
|
<sect1 id="using-utils">
|
|
<title>Cygwin Utilities</title>
|
|
|
|
<para>Cygwin comes with a number of command-line utilities that are used to
|
|
manage the UNIX emulation portion of the Cygwin environment. While many of
|
|
these reflect their UNIX counterparts, each was written specifically for
|
|
Cygwin. You may use the long or short option names interchangeably; for
|
|
example, <literal>--help</literal> and <literal>-h</literal> function
|
|
identically. All of the Cygwin command-line utilities support the
|
|
<literal>--help</literal> and <literal>--version</literal> options. </para>
|
|
|
|
<refentry id="cygcheck">
|
|
<refmeta>
|
|
<refentrytitle>cygcheck</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>cygcheck</refname>
|
|
<refpurpose>List system information, check installed packages, or query package database</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
cygcheck [-v] [-h] PROGRAM
|
|
cygcheck -c [-d] [PACKAGE]
|
|
cygcheck -s [-r] [-v] [-h]
|
|
cygcheck -k
|
|
cygcheck -f FILE [FILE]...
|
|
cygcheck -l [PACKAGE]...
|
|
cygcheck -p REGEXP
|
|
cygcheck --delete-orphaned-installation-keys
|
|
cygcheck -h
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="cygcheck-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
At least one command option or a PROGRAM is required, as shown above.
|
|
|
|
PROGRAM list library (DLL) dependencies of PROGRAM
|
|
-c, --check-setup show installed version of PACKAGE and verify integrity
|
|
(or for all installed packages if none specified)
|
|
-d, --dump-only just list packages, do not verify (with -c)
|
|
-s, --sysinfo produce diagnostic system information (implies -c -d)
|
|
-r, --registry also scan registry for Cygwin settings (with -s)
|
|
-k, --keycheck perform a keyboard check session (must be run from a
|
|
plain console only, not from a pty/rxvt/xterm)
|
|
-f, --find-package find the package to which FILE belongs
|
|
-l, --list-package list contents of PACKAGE (or all packages if none given)
|
|
-p, --package-query search for REGEXP in the entire cygwin.com package
|
|
repository (requires internet connectivity)
|
|
--delete-orphaned-installation-keys
|
|
Delete installation keys of old, now unused
|
|
installations from the registry. Requires the right
|
|
to change the registry.
|
|
-v, --verbose produce more verbose output
|
|
-h, --help annotate output with explanatory comments when given
|
|
with another command, otherwise print this help
|
|
-V, --version print the version of cygcheck and exit
|
|
|
|
Note: -c, -f, and -l only report on packages that are currently installed. To
|
|
search all official Cygwin packages use -p instead. The -p REGEXP matches
|
|
package names, descriptions, and names of files/paths within all packages.
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cygcheck-desc">
|
|
<title>Description</title>
|
|
<para> The <command>cygcheck</command> program is a diagnostic utility for
|
|
dealing with Cygwin programs. If you are familiar with
|
|
<command>dpkg</command> or <command>rpm</command>,
|
|
<command>cygcheck</command> is similar in many ways. (The major
|
|
difference is that <command>setup.exe</command> handles installing and
|
|
uninstalling packages; see <xref linkend="internet-setup"/> for more
|
|
information.) </para>
|
|
<para> The <literal>-c</literal> option checks the version and status of
|
|
installed Cygwin packages. If you specify one or more package names,
|
|
<command>cygcheck</command> will limit its output to those packages, or
|
|
with no arguments it lists all packages. A package will be marked
|
|
<literal>Incomplete</literal> if files originally installed are no longer
|
|
present. The best thing to do in that situation is reinstall the package
|
|
with <command>setup.exe</command>. To see which files are missing, use
|
|
the <literal>-v</literal> option. If you do not need to know the status
|
|
of each package and want <command>cygcheck</command> to run faster, add
|
|
the <literal>-d</literal> option and <command>cygcheck</command> will
|
|
only output the name and version for each package. </para>
|
|
<para> If you list one or more programs on the command line,
|
|
<command>cygcheck</command> will diagnose the runtime environment of that
|
|
program or programs, providing the names of DLL files on which the
|
|
program depends. If you specify the <literal>-s</literal> option,
|
|
<command>cygcheck</command> will give general system information. If you
|
|
list one or more programs on the command line and specify
|
|
<literal>-s</literal>, <command>cygcheck</command> will report on
|
|
both.</para>
|
|
<para> The <literal>-f</literal> option helps you to track down which
|
|
package a file came from, and <literal>-l</literal> lists all files in a
|
|
package. For example, to find out about
|
|
<filename>/usr/bin/less</filename> and its package:
|
|
</para>
|
|
|
|
<example
|
|
id="utils-cygcheck-ex"><title>Example <command>cygcheck</command>
|
|
usage</title>
|
|
<screen>
|
|
$ cygcheck -f /usr/bin/less
|
|
less-381-1
|
|
|
|
$ cygcheck -l less
|
|
/usr/bin/less.exe
|
|
/usr/bin/lessecho.exe
|
|
/usr/bin/lesskey.exe
|
|
/usr/man/man1/less.1
|
|
/usr/man/man1/lesskey.1
|
|
</screen>
|
|
</example>
|
|
|
|
<para>The <literal>-h</literal> option prints additional helpful messages
|
|
in the report, at the beginning of each section. It also adds table
|
|
column headings. While this is useful information, it also adds some to
|
|
the size of the report, so if you want a compact report or if you know
|
|
what everything is already, just leave this out.</para>
|
|
|
|
<para>The <literal>-v</literal> option causes the output to be more
|
|
verbose. What this means is that additional information will be reported
|
|
which is usually not interesting, such as the internal version numbers of
|
|
DLLs, additional information about recursive DLL usage, and if a file in
|
|
one directory in the PATH also occurs in other directories on the PATH. </para>
|
|
|
|
<para>The <literal>-r</literal> option causes <command>cygcheck</command>
|
|
to search your registry for information that is relevant to Cygwin
|
|
programs. These registry entries are the ones that have "Cygwin" in the
|
|
name. If you are paranoid about privacy, you may remove information from
|
|
this report, but please keep in mind that doing so makes it harder to
|
|
diagnose your problems.</para>
|
|
|
|
<para>In contrast to the other options that search the packages that are
|
|
installed on your local system, the <literal>-p</literal> option can be
|
|
used to search the entire official Cygwin package repository. It takes as
|
|
argument a Perl-compatible regular expression which is used to match
|
|
package names, package descriptions, and path/filenames of the contents
|
|
of packages. This feature requires an active internet connection, since
|
|
it must query the <literal>cygwin.com</literal> web site. In fact, it is
|
|
equivalent to the search that is available on the <ulink
|
|
url="https://cygwin.com/packages/">Cygwin package listing</ulink>
|
|
page.</para>
|
|
|
|
<para>For example, perhaps you are getting an error because you are missing
|
|
a certain DLL and you want to know which package includes that file:
|
|
</para>
|
|
|
|
<example id="utils-search-ex"><title>Searching all packages for a
|
|
file</title>
|
|
<screen>
|
|
$ cygcheck -p 'cygintl-2\.dll'
|
|
Found 1 matches for 'cygintl-2\.dll'.
|
|
|
|
libintl2-0.12.1-3 GNU Internationalization runtime library
|
|
|
|
$ cygcheck -p 'libexpat.*\.a'
|
|
Found 2 matches for 'libexpat.*\.a'.
|
|
|
|
expat-1.95.7-1 XML parser library written in C
|
|
expat-1.95.8-1 XML parser library written in C
|
|
|
|
$ cygcheck -p '/ls\.exe'
|
|
Found 2 matches for '/ls\.exe'.
|
|
|
|
coreutils-5.2.1-5 GNU core utilities (includes fileutils, sh-utils and textutils)
|
|
coreutils-5.3.0-6 GNU core utilities (includes fileutils, sh-utils and textutils)
|
|
</screen>
|
|
</example>
|
|
|
|
<para>Note that this option takes a regular expression, not a glob or
|
|
wildcard. This means that you need to use <literal>.*</literal> if you
|
|
want something similar to the wildcard <literal>*</literal> commonly used
|
|
in filename globbing. Similarly, to match the period character you should
|
|
use <literal>\.</literal> since the <literal>.</literal> character in a
|
|
regexp is a metacharacter that will match any character. Also be aware
|
|
that the characters such as <literal>\</literal> and <literal>*</literal>
|
|
are shell metacharacters, so they must be either escaped or quoted, as in
|
|
the example above.</para>
|
|
|
|
<para>The third example above illustrates that if you want to match a whole
|
|
filename, you should include the <literal>/</literal> path seperator. In
|
|
the given example this ensures that filenames that happen to end in
|
|
<literal>ls.exe</literal> such as <literal>ncftpls.exe</literal> are not
|
|
shown. Note that this use does not mean "look for packages with
|
|
<literal>ls</literal> in the root directory," since the
|
|
<literal>/</literal> can match anywhere in the path. It's just there to
|
|
anchor the match so that it matches a full filename.</para>
|
|
|
|
<para>By default the matching is case-sensitive. To get a case insensitive
|
|
match, begin your regexp with <literal>(?i)</literal> which is a
|
|
PCRE-specific feature. For complete documentation on Perl-compatible
|
|
regular expression syntax and options, read the <command>perlre</command>
|
|
manpage, or one of many websites such as <literal>perldoc.com</literal>
|
|
that document the Perl language.</para>
|
|
|
|
<para>The <command>cygcheck</command> program should be used to send
|
|
information about your system for troubleshooting when requested. When
|
|
asked to run this command save the output so that you can email it, for
|
|
example:</para>
|
|
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>cygcheck -s -v -r -h > cygcheck_output.txt</userinput>
|
|
</screen>
|
|
|
|
<para> Each Cygwin DLL stores its path and installation key in the
|
|
registry. This allows troubleshooting of problems which could be a result
|
|
of having multiple concurrent Cygwin installations. However, if you're
|
|
experimenting a lot with different Cygwin installation paths, your
|
|
registry could accumulate a lot of old Cygwin installation entries for
|
|
which the installation doesn't exist anymore. To get rid of these
|
|
orphaned registry entries, use the <command>cygcheck
|
|
--delete-orphaned-installation-keys</command> command.</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<refentry id="cygpath">
|
|
<refmeta>
|
|
<refentrytitle>cygpath</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>cygpath</refname>
|
|
<refpurpose>Convert Unix and Windows format paths, or output system path information</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME...
|
|
cygpath [-c HANDLE]
|
|
cygpath [-ADHOPSW]
|
|
cygpath [-F ID]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="cygpath-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
Output type options:
|
|
|
|
-d, --dos print DOS (short) form of NAMEs (C:\PROGRA~1\)
|
|
-m, --mixed like --windows, but with regular slashes (C:/WINNT)
|
|
-M, --mode report on mode of file (currently binmode or textmode)
|
|
-u, --unix (default) print Unix form of NAMEs (/cygdrive/c/winnt)
|
|
-w, --windows print Windows form of NAMEs (C:\WINNT)
|
|
-t, --type TYPE print TYPE form: 'dos', 'mixed', 'unix', or 'windows'
|
|
|
|
Path conversion options:
|
|
|
|
-a, --absolute output absolute path
|
|
-l, --long-name print Windows long form of NAMEs (with -w, -m only)
|
|
-p, --path NAME is a PATH list (i.e., '/bin:/usr/bin')
|
|
-U, --proc-cygdrive Emit /proc/cygdrive path instead of cygdrive prefix
|
|
when converting Windows path to UNIX path.
|
|
-s, --short-name print DOS (short) form of NAMEs (with -w, -m only)
|
|
-C, --codepage CP print DOS, Windows, or mixed pathname in Windows
|
|
codepage CP. CP can be a numeric codepage identifier,
|
|
or one of the reserved words ANSI, OEM, or UTF8.
|
|
If this option is missing, cygpath defaults to the
|
|
character set defined by the current locale.
|
|
|
|
System information:
|
|
|
|
-A, --allusers use `All Users' instead of current user for -D, -P
|
|
-D, --desktop output `Desktop' directory and exit
|
|
-H, --homeroot output `Profiles' directory (home root) and exit
|
|
-O, --mydocs output `My Documents' directory and exit
|
|
-P, --smprograms output Start Menu `Programs' directory and exit
|
|
-S, --sysdir output system directory and exit
|
|
-W, --windir output `Windows' directory and exit
|
|
-F, --folder ID output special folder with numeric ID and exit
|
|
|
|
Other options:
|
|
|
|
-f, --file FILE read FILE for input; use - to read from STDIN
|
|
-o, --option read options from FILE as well (for use with --file)
|
|
-c, --close HANDLE close HANDLE (for use in captured process)
|
|
-i, --ignore ignore missing argument
|
|
-h, --help output usage information and exit
|
|
-V, --version output version information and exit
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="cygpath-desc">
|
|
<title>Description</title>
|
|
<para>The <command>cygpath</command> program is a utility that converts
|
|
Windows native filenames to Cygwin POSIX-style pathnames and vice versa.
|
|
It can be used when a Cygwin program needs to pass a file name to a
|
|
native Windows program, or expects to get a file name from a native
|
|
Windows program. Alternatively, <command>cygpath</command> can output
|
|
information about the location of important system directories in either
|
|
format. </para>
|
|
|
|
<para>The <literal>-u</literal> and <literal>-w</literal> options indicate
|
|
whether you want a conversion to UNIX (POSIX) format
|
|
(<literal>-u</literal>) or to Windows format (<literal>-w</literal>). Use
|
|
the <literal>-d</literal> to get DOS-style (8.3) file and path names. The
|
|
<literal>-m</literal> option will output Windows-style format but with
|
|
forward slashes instead of backslashes. This option is especially useful
|
|
in shell scripts, which use backslashes as an escape character.</para>
|
|
|
|
<para> In combination with the <literal>-w</literal> option, you can use
|
|
the <literal>-l</literal> and <literal>-s</literal> options to use normal
|
|
(long) or DOS-style (short) form. The <literal>-d</literal> option is
|
|
identical to <literal>-w</literal> and <literal>-s</literal> together. </para>
|
|
|
|
<para>The <literal>-C</literal> option allows to specify a Windows codepage
|
|
to print DOS and Windows paths created with one of the
|
|
<literal>-d</literal>, <literal>-m</literal>, or <literal>-w</literal>
|
|
options. The default is to use the character set of the current locale
|
|
defined by one of the internationalization environment variables
|
|
<envar>LC_ALL</envar>, <envar>LC_CTYPE</envar>, or <envar>LANG</envar>,
|
|
see <xref linkend="setup-locale"/>. This is sometimes not sufficient for
|
|
interaction with native Windows tools, which might expect native,
|
|
non-ASCII characters in a specific Windows codepage. Console tools, for
|
|
instance, might expect pathnames in the current OEM codepage, while
|
|
graphical tools like Windows Explorer might expect pathnames in the
|
|
current ANSI codepage.</para>
|
|
|
|
<para>The <literal>-U</literal> option allows to use cygpath to create
|
|
unambiguous Unix paths pointing outside the Cygwin tree andf thus having
|
|
no explicit POSIX path. Those paths usually use the cygdrive prefix.
|
|
However, the cygdrive prefix can be changed by the user, so symbolic links
|
|
created using the cygdrive prefix are not foolproof. With
|
|
<literal>-U</literal> cygpath will generate such paths prepended by the
|
|
virtual <filename>/proc/cygdrive</filename> symbolic link, which will
|
|
never change, so the created path is safe against changing the cygdrive
|
|
prefix.</para>
|
|
|
|
<para>The <literal>-C</literal> option takes a single parameter:</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para><literal>ANSI</literal>, to specify the current ANSI
|
|
codepage</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>OEM</literal>, to specify the current OEM (console)
|
|
codepage</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><literal>UTF8</literal>, to specify UTF-8.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>A numerical, decimal codepage number, for instance 936 for GBK,
|
|
28593 for ISO-8859-3, etc. A full list of supported codepages is
|
|
listed on the Microsoft MSDN page <ulink
|
|
url="http://msdn.microsoft.com/en-us/library/dd317756(VS.85).aspx"
|
|
>Code Page Identifiers</ulink>. A codepage of 0 is the same as if the
|
|
<literal>-C</literal> hasn't been specified at all.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The <literal>-p</literal> option means that you want to convert a
|
|
path-style string rather than a single filename. For example, the PATH
|
|
environment variable is semicolon-delimited in Windows, but
|
|
colon-delimited in UNIX. By giving <literal>-p</literal> you are
|
|
instructing <command>cygpath</command> to convert between these
|
|
formats.</para>
|
|
|
|
<para>The <literal>-i</literal> option supresses the print out of the usage
|
|
message if no filename argument was given. It can be used in make file
|
|
rules converting variables that may be omitted to a proper format. Note
|
|
that <command>cygpath</command> output may contain spaces (C:\Program
|
|
Files) so should be enclosed in quotes. </para>
|
|
|
|
|
|
<example id="utils-cygpath-ex">
|
|
<title>Example <command>cygpath</command> usage</title>
|
|
<screen>
|
|
<![CDATA[
|
|
#!/bin/sh
|
|
if [ "${1}" = "" ];
|
|
then
|
|
XPATH=".";
|
|
else
|
|
XPATH="$(cygpath -C ANSI -w "${1}")";
|
|
fi
|
|
explorer $XPATH &
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>The capital options <literal>-D</literal>, <literal>-H</literal>,
|
|
<literal>-P</literal>, <literal>-S</literal>, and <literal>-W</literal>
|
|
output directories used by Windows that are not the same on all systems,
|
|
for example <literal>-S</literal> might output C:\WINNT\system32 or
|
|
C:\Windows\System32. The <literal>-H</literal> shows the Windows profiles
|
|
directory that can be used as root of home. The <literal>-A</literal>
|
|
option forces use of the "All Users" directories instead of the current
|
|
user for the <literal>-D</literal>, <literal>-O</literal> and
|
|
<literal>-P</literal> options. The <literal>-F</literal> outputs other
|
|
special folders specified by their internal numeric code (decimal or
|
|
0x-prefixed hex). For valid codes and symbolic names, see the CSIDL_*
|
|
definitions in the include file /usr/include/w32api/shlobj.h from package
|
|
w32api. The current valid range of codes for folders is 0 (Desktop) to 59
|
|
(CDBurn area). By default the output is in UNIX (POSIX) format; use the
|
|
<literal>-w</literal> or <literal>-d</literal> options to get other
|
|
formats.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="dumper">
|
|
<refmeta>
|
|
<refentrytitle>dumper</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>dumper</refname>
|
|
<refpurpose>Dump core from WIN32PID to FILENAME.core</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
dumper [OPTION] FILENAME WIN32PID
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="dumper-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-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>
|
|
</refsect1>
|
|
|
|
<refsect1 id="dumper-desc">
|
|
<title>Description</title>
|
|
<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>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="getconf">
|
|
<refmeta>
|
|
<refentrytitle>getconf</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>getconf</refname>
|
|
<refpurpose>Get configuration values</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
getconf [-v specification] variable_name [pathname]
|
|
getconf -a [pathname]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="getconf-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-v specification Indicate specific version for which configuration
|
|
values shall be fetched.
|
|
-a, --all Print all known configuration values
|
|
|
|
Other options:
|
|
|
|
-h, --help This text
|
|
-V, --version Print program version and exit
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="getconf-desc">
|
|
<title>Description</title>
|
|
<para>The <command>getconf</command> utility prints the value of the
|
|
configuration variable specified by <literal>variable_name</literal>. If
|
|
no <literal>pathname</literal> is given, <command>getconf</command>
|
|
serves as a wrapper for the <literal>confstr</literal> and
|
|
<literal>sysconf</literal> functions, supporting the symbolic constants
|
|
defined in the <literal>limits.h</literal> and
|
|
<literal>unistd.h</literal> headers, without their respective
|
|
<literal>_CS_</literal> or <literal>_SC_</literal> prefixes. </para>
|
|
|
|
<para>If <literal>pathname</literal> is given, <command>getconf</command>
|
|
prints the value of the configuration variable for the specified
|
|
pathname. In this form, <command>getconf</command> serves as a wrapper
|
|
for the <literal>pathconf</literal> function, supporting the symbolic
|
|
constants defined in the <literal>unistd.h</literal> header, without the
|
|
<literal>_PC_</literal> prefix. </para>
|
|
|
|
<para>If you specify the <literal>-v</literal> option, the parameter
|
|
denotes a specification for which the value of the configuration variable
|
|
should be printed. Note that the only specifications supported by Cygwin
|
|
are <literal>POSIX_V7_ILP32_OFFBIG</literal> and the legacy
|
|
<literal>POSIX_V6_ILP32_OFFBIG</literal> and
|
|
<literal>XBS5_ILP32_OFFBIG</literal> equivalents.</para>
|
|
|
|
<para>Use the <literal>-a</literal> option to print a list of all available
|
|
configuration variables for the system, or given
|
|
<literal>pathname</literal>, and their values.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="getfacl">
|
|
<refmeta>
|
|
<refentrytitle>getfacl</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>getfacl</refname>
|
|
<refpurpose>Display file and directory access control lists (ACLs)</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
getfacl [-adceEn] FILE [FILE2...]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="getfacl-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-a, --access display the file access control list only
|
|
-d, --default display the default access control list only
|
|
-c, --omit-header do not display the comment header
|
|
-e, --all-effective print all effective rights
|
|
-E, --no-effective print no effective rights
|
|
-n, --numeric print numeric user/group identifiers
|
|
-V, --version print version and exit
|
|
-h, --help this help text
|
|
|
|
When multiple files are specified on the command line, a blank
|
|
line separates the ACLs for each file.
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="getfacl-desc">
|
|
<title>Description</title>
|
|
<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, the setuid (s), setgid (s),
|
|
and sticky (t) bits if available, and both the ACL and the default ACL,
|
|
if it exists. For more information on Cygwin and Windows ACLs, see
|
|
<xref linkend="ntsec"/> in the Cygwin User's Guide. The format
|
|
for ACL output is as follows:
|
|
<screen>
|
|
# file: filename
|
|
# owner: name or uid
|
|
# group: name or uid
|
|
# flags: sst
|
|
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>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="kill">
|
|
<refmeta>
|
|
<refentrytitle>kill</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>kill</refname>
|
|
<refpurpose>Send signals to processes</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
kill [-f] [-signal] [-s signal] pid1 [pid2 ...]
|
|
kill -l [signal]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="kill-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-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>
|
|
</refsect1>
|
|
|
|
<refsect1 id="kill-desc">
|
|
<title>Description</title>
|
|
<para>The <command>kill</command> program allows you to send arbitrary
|
|
signals to other Cygwin programs. The usual purpose is to end a running
|
|
program from some other window when ^C won't work, but you can also send
|
|
program-specified signals such as SIGUSR1 to trigger actions within the
|
|
program, like enabling debugging or re-opening log files. Each program
|
|
defines the signals they understand.</para>
|
|
|
|
<para>You may need to specify the full path to use <command>kill</command>
|
|
from within some shells, including <command>bash</command>, the default
|
|
Cygwin shell. This is because <command>bash</command> defines a
|
|
<command>kill</command> builtin function; see the <command>bash</command>
|
|
man page under <emphasis>BUILTIN COMMANDS</emphasis> for more
|
|
information. To make sure you are using the Cygwin version, try
|
|
<screen>
|
|
$ /bin/kill --version
|
|
</screen> which should give the Cygwin
|
|
<command>kill</command> version number and copyright information. </para>
|
|
|
|
<para>Unless you specific the <literal>-f</literal> option, the "pid"
|
|
values used by <command>kill</command> are the Cygwin pids, not the
|
|
Windows pids. To get a list of running programs and their Cygwin pids,
|
|
use the Cygwin <command>ps</command> program. <command>ps -W</command>
|
|
will display <emphasis>all</emphasis> windows pids.</para>
|
|
|
|
<para>The <command>kill -l</command> option prints the name of the given
|
|
signal, or a list of all signal names if no signal is given.</para>
|
|
|
|
<para>To send a specific signal, use the <literal>-signN</literal> option,
|
|
either with a signal number or a signal name (minus the "SIG" part), as
|
|
shown in these examples:</para>
|
|
|
|
<example id="utils-kill-ex">
|
|
<title>Using the kill command</title>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>kill 123</userinput>
|
|
<prompt>$</prompt> <userinput>kill -1 123</userinput>
|
|
<prompt>$</prompt> <userinput>kill -HUP 123</userinput>
|
|
<prompt>$</prompt> <userinput>kill -f 123</userinput>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>Here is a list of available signals, their numbers, and some
|
|
commentary on them, from the file
|
|
<literal><sys/signal.h></literal>, which should be considered the
|
|
official source of this information.</para>
|
|
|
|
<screen>
|
|
SIGHUP 1 hangup
|
|
SIGINT 2 interrupt
|
|
SIGQUIT 3 quit
|
|
SIGILL 4 illegal instruction (not reset when caught)
|
|
SIGTRAP 5 trace trap (not reset when caught)
|
|
SIGABRT 6 used by abort
|
|
SIGIOT 6 another name for SIGABRT
|
|
SIGEMT 7 EMT instruction
|
|
SIGFPE 8 floating point exception
|
|
SIGKILL 9 kill (cannot be caught or ignored)
|
|
SIGBUS 10 bus error
|
|
SIGSEGV 11 segmentation violation
|
|
SIGSYS 12 bad argument to system call
|
|
SIGPIPE 13 write on a pipe with no one to read it
|
|
SIGALRM 14 alarm clock
|
|
SIGTERM 15 software termination signal from kill
|
|
SIGURG 16 urgent condition on IO channel
|
|
SIGSTOP 17 sendable stop signal not from tty
|
|
SIGTSTP 18 stop signal from tty
|
|
SIGCONT 19 continue a stopped process
|
|
SIGCHLD 20 to parent on child stop or exit
|
|
SIGCLD 20 System V name for SIGCHLD
|
|
SIGTTIN 21 to readers pgrp upon background tty read
|
|
SIGTTOU 22 like TTIN for output if (tp->t_local&LTOSTOP)
|
|
SIGIO 23 input/output possible
|
|
SIGPOLL 23 System V name for SIGIO
|
|
SIGXCPU 24 exceeded CPU time limit
|
|
SIGXFSZ 25 exceeded file size limit
|
|
SIGVTALRM 26 virtual time alarm
|
|
SIGPROF 27 profiling time alarm
|
|
SIGWINCH 28 window changed
|
|
SIGLOST 29 resource lost (eg, record-lock lost)
|
|
SIGPWR 29 power failure
|
|
SIGUSR1 30 user defined signal 1
|
|
SIGUSR2 31 user defined signal 2
|
|
</screen>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ldd">
|
|
<refmeta>
|
|
<refentrytitle>ldd</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>ldd</refname>
|
|
<refpurpose>Print shared library dependencies</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
ldd [OPTION]... FILE...
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="ldd-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-h, --help print this help and exit
|
|
-V, --version print version information and exit
|
|
-r, --function-relocs process data and function relocations
|
|
(currently unimplemented)
|
|
-u, --unused print unused direct dependencies
|
|
(currently unimplemented)
|
|
-v, --verbose print all information
|
|
(currently unimplemented)
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="ldd-desc">
|
|
<title>Description</title>
|
|
<para><command>ldd</command> prints the shared libraries (DLLs) loaded
|
|
when running an executable or DLL.</para>
|
|
|
|
<refsect2 id="ldd-desc-security">
|
|
<title>Security</title>
|
|
<para>
|
|
<command>ldd</command> invokes the Windows loader on the file specified,
|
|
then uses the Windows debugging interface to report DLLs loaded, and
|
|
(for executables) to attempt to stop execution before the entrypoint.
|
|
Thus, you should never use ldd on an untrusted file.
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<refentry id="locale">
|
|
<refmeta>
|
|
<refentrytitle>locale</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>locale</refname>
|
|
<refpurpose>Get locale-specific information</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
locale [-amvhV]
|
|
locale [-ck] NAME
|
|
locale [-iusfnU]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="locale-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
System information:
|
|
|
|
-a, --all-locales List all available supported locales
|
|
-m, --charmaps List all available character maps
|
|
-v, --verbose More verbose output
|
|
|
|
Modify output format:
|
|
|
|
-c, --category-name List information about given category NAME
|
|
-k, --keyword-name Print information about given keyword NAME
|
|
|
|
Default locale information:
|
|
|
|
-i, --input Print current input locale
|
|
-u, --user Print locale of user's default UI language
|
|
-s, --system Print locale of system default UI language
|
|
-f, --format Print locale of user's regional format settings
|
|
(time, numeric & monetary)
|
|
-n, --no-unicode Print system default locale for non-Unicode programs
|
|
-U, --utf Attach \".UTF-8\" to the result
|
|
|
|
Other options:
|
|
|
|
-h, --help This text
|
|
-V, --version Print program version and exit
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="locale-desc">
|
|
<title>Description</title>
|
|
<para><command>locale</command> without parameters prints information about
|
|
the current locale environment settings.</para>
|
|
|
|
<para>The <literal>-i</literal>, <literal>-u</literal>,
|
|
<literal>-s</literal>, <literal>-f</literal>, and <literal>-n</literal>
|
|
options can be used to request the various Windows locale settings. The
|
|
purpose is to use this command in scripts to set the POSIX locale
|
|
variables.</para>
|
|
|
|
<para>The <literal>-i</literal> option prints the current input language.
|
|
This is called the "Input language" and basically equivalent to the
|
|
current keyboard layout setting.</para>
|
|
|
|
<para>The <literal>-u</literal> option prints the current user's Windows UI
|
|
locale to stdout. In Windows this setting is called the
|
|
"Display Language".</para>
|
|
|
|
<para>The <literal>-s</literal> option prints the systems default instead.
|
|
</para>
|
|
|
|
<para>The <literal>-f</literal> option prints the user's setting for time,
|
|
date, number and currency. That's equivalent to the setting in the
|
|
"Formats" or "Regional Options" tab in the "Region and Language" or
|
|
"Regional and Language Options" dialog.</para>
|
|
|
|
<para>The <literal>-n</literal> option prints the system's default
|
|
language used for applications which don't support Unicode.</para>
|
|
|
|
<para>With the <literal>-U</literal> option <command>locale</command>
|
|
appends the string ".UTF-8" to enforce using UTF-8. Using UTF-8
|
|
as codeset is recommended.</para>
|
|
|
|
<para>Usage example:</para>
|
|
|
|
<screen>
|
|
bash$ export LANG=$(locale -uU)
|
|
bash$ echo $LANG
|
|
en_US.UTF-8
|
|
bash$ export LC_TIME=$(locale -fU)
|
|
bash$ echo $LC_TIME
|
|
de_DE.UTF-8
|
|
</screen>
|
|
|
|
<para>The <literal>-a</literal> option is helpful to learn which locales
|
|
are supported by your Windows machine. It prints all available locales
|
|
and the allowed modifiers. Example:</para>
|
|
|
|
<screen>
|
|
bash$ locale -a
|
|
C
|
|
C.utf8
|
|
POSIX
|
|
af_ZA
|
|
af_ZA.utf8
|
|
am_ET
|
|
am_ET.utf8
|
|
...
|
|
be_BY
|
|
be_BY.utf8
|
|
be_BY@latin
|
|
...
|
|
ca_ES
|
|
ca_ES.utf8
|
|
ca_ES@euro
|
|
catalan
|
|
...
|
|
</screen>
|
|
|
|
<para>The <literal>-v</literal> option prints more detailed information
|
|
about each available locale. Example:</para>
|
|
|
|
<screen>
|
|
bash$ locale -av
|
|
locale: af_ZA archive: /cygdrive/c/Windows/system32/kernel32.dll
|
|
-------------------------------------------------------------------------------
|
|
language | Afrikaans
|
|
territory | South Africa
|
|
codeset | ISO-8859-1
|
|
|
|
locale: af_ZA.utf8 archive: /cygdrive/c/Windows/system32/kernel32.dll
|
|
-------------------------------------------------------------------------------
|
|
language | Afrikaans
|
|
territory | South Africa
|
|
codeset | UTF-8
|
|
|
|
...
|
|
|
|
locale: ca_ES@euro archive: /cygdrive/c/Windows/system32/kernel32.dll
|
|
-------------------------------------------------------------------------------
|
|
language | Catalan
|
|
territory | Spain
|
|
codeset | ISO-8859-15
|
|
|
|
locale: catalan archive: /usr/share/locale/locale.alias
|
|
-------------------------------------------------------------------------------
|
|
language | Catalan
|
|
territory | Spain
|
|
codeset | ISO-8859-1
|
|
|
|
...
|
|
</screen>
|
|
|
|
<para>The <literal>-m</literal> option prints the names of the available
|
|
charmaps supported by Cygwin to stdout.</para>
|
|
|
|
<para>Otherwise, if arguments are given, <command>locale</command> prints
|
|
the values assigned to these arguments. Arguments can be names of locale
|
|
categories (for instance: LC_CTYPE, LC_MONETARY), or names of keywords
|
|
supported in the locale categories (for instance: thousands_sep,
|
|
charmap). The <literal>-c</literal> option prints additionally the name
|
|
of the category. The <literal>-k</literal> option prints additionally the
|
|
name of the keyword. Example:</para>
|
|
|
|
<screen>
|
|
bash$ locale -ck LC_MESSAGES
|
|
LC_MESSAGES
|
|
yesexpr="^[yY]"
|
|
noexpr="^[nN]"
|
|
yesstr="yes"
|
|
nostr="no"
|
|
messages-codeset="UTF-8"
|
|
bash$ locale noexpr
|
|
^[nN]
|
|
</screen>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="minidumper">
|
|
<refmeta>
|
|
<refentrytitle>minidumper</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>minidumper</refname>
|
|
<refpurpose>Write minidump from WIN32PID to FILENAME.dmp</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
minidumper [OPTION] FILENAME WIN32PID
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="minidumper-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-t, --type minidump type flags
|
|
-n, --nokill don't terminate the dumped process
|
|
-d, --verbose be verbose while dumping
|
|
-h, --help output help information and exit
|
|
-q, --quiet be quiet while dumping (default)
|
|
-V, --version output version information and exit
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="minidumper-desc">
|
|
<title>Description</title>
|
|
<para>
|
|
The <command>minidumper</command> utility can be used to create a
|
|
minidump of a running Windows process. This minidump can be later
|
|
analysed using breakpad or Windows debugging tools.
|
|
</para>
|
|
|
|
<para>
|
|
<command>minidumper</command> can be used with cygwin's Just-In-Time
|
|
debugging facility in exactly the same way as <command>dumper</command>
|
|
(See <xref linkend="dumper"></xref>).
|
|
</para>
|
|
|
|
<para>
|
|
<command>minidumper</command> can also be started from the command line to
|
|
create a minidump of any running process. For compatibility with
|
|
<command>dumper</command> the target process is terminated after dumping
|
|
unless the <literal>-n</literal> option is given.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="mkgroup">
|
|
<refmeta>
|
|
<refentrytitle>mkgroup</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>mkgroup</refname>
|
|
<refpurpose>Write /etc/group-like output to stdout</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
mkgroup [OPTION]...
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="mkgroup-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
Options:
|
|
|
|
-l,--local [machine] Print local group accounts of \"machine\",
|
|
from local machine if no machine specified.
|
|
Automatically adding machine prefix for local
|
|
machine depends on settings in /etc/nsswitch.conf.
|
|
-L,--Local machine Ditto, but generate groupname with machine prefix.
|
|
-d,--domain [domain] Print domain groups,
|
|
from current domain if no domain specified.
|
|
-c,--current Print current group.
|
|
-S,--separator char For -L use character char as domain\\group
|
|
separator in groupname instead of default '+'.
|
|
-o,--id-offset offset Change the default offset (0x10000) added to gids
|
|
-g,--group groupname Only return information for the specified group.
|
|
One of -l, -d must be specified, too.
|
|
-b,--no-builtin Don't print BUILTIN groups.
|
|
-U,--unix grouplist Print UNIX groups when using -l on a UNIX Samba
|
|
server. Grouplist is a comma-separated list of
|
|
groupnames or gid ranges (root,-25,50-100).
|
|
Enumerating large ranges can take a long time!
|
|
-h,--help Print this message.
|
|
-v,--version Print version information and exit.
|
|
|
|
Default is to print local groups on stand-alone machines, plus domain
|
|
groups on domain controllers and domain member machines.
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkgroup-desc">
|
|
<title>Description</title>
|
|
<para>Don't use this command to generate a local /etc/group file, unless you
|
|
really need one. See the Cygwin User's Guide for more information.
|
|
</para>
|
|
|
|
<para>The <command>mkgroup</command> program can be used to create a local
|
|
<filename>/etc/group</filename> file. Cygwin doesn't need this file,
|
|
because it reads group information from the Windows account databases,
|
|
but you can add an <filename>/etc/group</filename> file for instance, if
|
|
your machine is often disconnected from its domain controller.
|
|
</para>
|
|
|
|
<para>Note that this information is static, in contrast to the information
|
|
automatically gathered by Cygwin from the Windows account databases. If
|
|
you change the group information on your system, you'll need to regenerate
|
|
the group file for it to have the new information.</para>
|
|
|
|
<para>By default, the information generated by <command>mkgroup</command>
|
|
is equivalent to the information generated by Cygwin itself. The
|
|
<literal>-d</literal> and <literal>-l/-L</literal> options allow you to
|
|
specify where the information comes from, some domain, or the local SAM
|
|
of a machine. Note that you can only enumerate accounts from trusted
|
|
domains. Any non-trusted domain will be ignored. Access-restrictions
|
|
of your current account apply. The <literal>-l/-L</literal> when used
|
|
with a machine name, tries to contact that machine to enumerate local
|
|
groups of other machines, typically outside of domains. This scenario
|
|
cannot be covered by Cygwin's account automatism. If you want to use
|
|
the <literal>-L</literal> option, but you don't like the default
|
|
domain/group separator from <filename>/etc/nsswitch.conf</filename>,
|
|
you can specify another separator using the <literal>-S</literal> option,
|
|
for instance:</para>
|
|
|
|
<example id="utils-mkgroup-ex">
|
|
<title>Setting up group entry for current user with different
|
|
domain/group separator</title>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>mkgroup -L server1 -S= > /etc/group</userinput>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>For very simple needs, an entry for the current user's group can be
|
|
created by using the option <literal>-c</literal>.</para>
|
|
|
|
<para>The <literal>-o</literal> option allows for (unlikely) special cases
|
|
with multiple machines where the GIDs might match otherwise. The
|
|
<literal>-g</literal> option only prints the information for one group.
|
|
The <literal>-U</literal> option allows you to enumerate the standard
|
|
UNIX groups on a Samba machine. It's used together with <literal>-l
|
|
samba-server</literal> or <literal>-L samba-server</literal>. The normal
|
|
UNIX groups are usually not enumerated, but they can show up as a group
|
|
in <command>ls -l</command> output. </para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="mkpasswd">
|
|
<refmeta>
|
|
<refentrytitle>mkpasswd</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>mkpasswd</refname>
|
|
<refpurpose>Write /etc/passwd-like output to stdout</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
mkpasswd [OPTIONS]...
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="mkpasswd-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
Options:
|
|
|
|
-l,--local [machine] Print local user accounts of \"machine\",
|
|
from local machine if no machine specified.
|
|
Automatically adding machine prefix for local
|
|
machine depends on settings in /etc/nsswitch.conf.
|
|
-L,--Local machine Ditto, but generate username with machine prefix.
|
|
-d,--domain [domain] Print domain accounts,
|
|
from current domain if no domain specified.
|
|
-c,--current Print current user.
|
|
-S,--separator char For -L use character char as domain\\user
|
|
separator in username instead of the default '+'.
|
|
-o,--id-offset offset Change the default offset (0x10000) added to uids
|
|
of foreign local machine accounts. Use with -l/-L.
|
|
-u,--username username Only return information for the specified user.
|
|
One of -l, -d must be specified, too
|
|
-b,--no-builtin Don't print BUILTIN users.
|
|
-p,--path-to-home path Use specified path instead of user account home dir
|
|
or /home prefix.
|
|
-U,--unix userlist Print UNIX users when using -l on a UNIX Samba
|
|
server. Userlist is a comma-separated list of
|
|
usernames or uid ranges (root,-25,50-100).
|
|
Enumerating large ranges can take a long time!
|
|
-h,--help Displays this message.
|
|
-V,--version Version information and exit.
|
|
|
|
Default is to print local accounts on stand-alone machines, domain accounts
|
|
on domain controllers and domain member machines.
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mkpasswd-desc">
|
|
<title>Description</title>
|
|
<para>Don't use this command to generate a local /etc/passwd file, unless you
|
|
really need one. See the Cygwin User's Guide for more information.</para>
|
|
|
|
<para>The <command>mkpasswd</command> program can be used to create a
|
|
<filename>/etc/passwd</filename> file. Cygwin doesn't need this file,
|
|
because it reads user information from the Windows account databases,
|
|
but you can add an <filename>/etc/passwd</filename> file, for instance
|
|
if your machine is often disconnected from its domain controller.</para>
|
|
|
|
<para>Note that this information is static, in contrast to the information
|
|
automatically gathered by Cygwin from the Windows account databases. If
|
|
you change the user information on your system, you'll need to regenerate
|
|
the passwd file for it to have the new information.</para>
|
|
|
|
<para>By default, the information generated by <command>mkpasswd</command>
|
|
is equivalent to the information generated by Cygwin itself. The
|
|
<literal>-d</literal> and <literal>-l/-L</literal> options allow you to
|
|
specify where the information comes from, some domain, or the local SAM
|
|
of a machine. Note that you can only enumerate accounts from trusted
|
|
domains. Any non-trusted domain will be ignored. Access-restrictions
|
|
of your current account apply. The <literal>-l/-L</literal> when used
|
|
with a machine name, tries to contact that machine to enumerate local
|
|
groups of other machines, typically outside of domains. This scenario
|
|
cannot be covered by Cygwin's account automatism. If you want to use
|
|
the <literal>-L</literal> option, but you don't like the default
|
|
domain/group separator from <filename>/etc/nsswitch.conf</filename>,
|
|
you can specify another separator using the <literal>-S</literal> option,
|
|
analog to <command>mkgroup</command>.</para>
|
|
|
|
<para>For very simple needs, an entry for the current user can be created
|
|
by using the option <literal>-c</literal>.</para>
|
|
|
|
<para>The <literal>-o</literal> option allows for special cases (such as
|
|
multiple domains) where the UIDs might match otherwise. The
|
|
<literal>-p</literal> option causes <command>mkpasswd</command> to use
|
|
the specified prefix instead of the account home dir or <literal>/home/
|
|
</literal>. For example, this command:
|
|
</para>
|
|
|
|
<example id="utils-althome-ex"
|
|
><title>Using an alternate home root</title>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>mkpasswd -l -p "$(cygpath -H)" > /etc/passwd</userinput>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>
|
|
would put local users' home directories in the Windows
|
|
'Profiles' directory. The <literal>-u</literal> option creates just an
|
|
entry for the specified user. The <literal>-U</literal> option allows you
|
|
to enumerate the standard UNIX users on a Samba machine. It's used
|
|
together with <literal>-l samba-server</literal> or <literal>-L
|
|
samba-server</literal>. The normal UNIX users are usually not enumerated,
|
|
but they can show up as file owners in <command>ls -l</command> output.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="mount">
|
|
<refmeta>
|
|
<refentrytitle>mount</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>mount</refname>
|
|
<refpurpose>Display information about mounted filesystems, or mount a filesystem</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
mount [OPTION] [<win32path> <posixpath>]
|
|
mount -a
|
|
mount <posixpath>
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="mount-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-a, --all mount all filesystems mentioned in fstab
|
|
-c, --change-cygdrive-prefix change the cygdrive path prefix to <posixpath>
|
|
-f, --force force mount, don't warn about missing mount
|
|
point directories
|
|
-h, --help output usage information and exit
|
|
-m, --mount-entries write fstab entries to replicate mount points
|
|
and cygdrive prefixes
|
|
-o, --options X[,X...] specify mount options
|
|
-p, --show-cygdrive-prefix show user and/or system cygdrive path prefix
|
|
-V, --version output version information and exit
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="mount-desc">
|
|
<title>Description</title>
|
|
<para>The <command>mount</command> program is used to map your drives and
|
|
shares onto Cygwin's simulated POSIX directory tree, much like as is done
|
|
by mount commands on typical UNIX systems. However, in contrast to mount
|
|
points given in <filename>/etc/fstab</filename>, mount points created or
|
|
changed with <command>mount</command> are not persistent. They disappear
|
|
immediately after the last process of the current user exited. Please see
|
|
<xref linkend="mount-table"/> for more information on the concepts behind
|
|
the Cygwin POSIX file system and strategies for using mounts. To remove
|
|
mounts temporarily, use <command>umount</command></para>
|
|
|
|
<refsect2 id="utils-mount">
|
|
<title>Using mount</title>
|
|
|
|
<para>If you just type <command>mount</command> with no parameters, it
|
|
will display the current mount table for you.</para>
|
|
|
|
<example id="utils-mount-ex">
|
|
<title>Displaying the current set of mount points</title>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>mount</userinput>
|
|
C:/cygwin/bin on /usr/bin type ntfs (binary)
|
|
C:/cygwin/lib on /usr/lib type ntfs (binary)
|
|
C:/cygwin on / type ntfs (binary)
|
|
C: on /mnt/c type ntfs (binary,user,noumount)
|
|
D: on /mnt/d type fat (binary,user,noumount)
|
|
</screen>
|
|
</example>
|
|
|
|
<para>In this example, c:/cygwin is the POSIX root and the D drive is
|
|
mapped to <filename>/mnt/d</filename>. Note that in this case, the root
|
|
mount is a system-wide mount point that is visible to all users running
|
|
Cygwin programs, whereas the <filename>/mnt/d</filename> mount is only
|
|
visible to the current user.</para>
|
|
|
|
<para>The <command>mount</command> utility is also the mechanism for
|
|
adding new mounts to the mount table in memory. The following example
|
|
demonstrates how to mount the directory
|
|
<filename>//pollux/home/joe/data</filename> to
|
|
<filename>/data</filename> for the duration of the current session. </para>
|
|
|
|
<example id="utils-mount-add-ex">
|
|
<title>Adding mount points</title>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>ls /data</userinput>
|
|
ls: /data: No such file or directory
|
|
<prompt>$</prompt> <userinput>mount //pollux/home/joe/data /data</userinput>
|
|
mount: warning - /data does not exist!
|
|
<prompt>$</prompt> <userinput>mount</userinput>
|
|
//pollux/home/joe/data on /data type smbfs (binary)
|
|
C:/cygwin/bin on /usr/bin type ntfs (binary)
|
|
C:/cygwin/lib on /usr/lib type ntfs (binary)
|
|
C:/cygwin on / type ntfs (binary)
|
|
C: on /c type ntfs (binary,user,noumount)
|
|
D: on /d type fat (binary,user,noumount)
|
|
</screen>
|
|
</example>
|
|
|
|
<para>A given POSIX path may only exist once in the mount table. Attempts
|
|
to replace the mount will fail with a busy error. The
|
|
<literal>-f</literal> (force) option causes the old mount to be
|
|
silently replaced with the new one, provided the old mount point was a
|
|
user mount point. It's not valid to replace system-wide mount points.
|
|
Additionally, the <literal>-f</literal> option will silence warnings
|
|
about the non-existence of directories at the Win32 path
|
|
location.</para>
|
|
|
|
<para> The <literal>-o</literal> option is the method via which various
|
|
options about the mount point may be recorded. The following options
|
|
are available (note that most of the options are duplicates of other
|
|
mount flags):</para>
|
|
|
|
<screen>
|
|
acl - Use the filesystem's access control lists (ACLs) to
|
|
implement real POSIX permissions (default).
|
|
binary - Files default to binary mode (default).
|
|
bind - Allows to remount part of the file hierarchy somewhere else.
|
|
Different from other mount calls, the first argument
|
|
specifies an absolute POSIX path, rather than a Win32 path.
|
|
This POSIX path is remounted to the POSIX path specified as
|
|
the second parameter. The conversion to a Win32 path is done
|
|
within Cygwin immediately at the time of the call. Note that
|
|
symlinks are ignored while performing this path conversion.
|
|
cygexec - Treat all files below mount point as cygwin executables.
|
|
dos - Always convert leading spaces and trailing dots and spaces to
|
|
characters in the UNICODE private use area. This allows to use
|
|
broken filesystems which only allow DOS filenames, even if they
|
|
are not recognized as such by Cygwin.
|
|
exec - Treat all files below mount point as executable.
|
|
ihash - Always fake inode numbers rather than using the ones returned
|
|
by the filesystem. This allows to use broken filesystems which
|
|
don't return unambiguous inode numbers, even if they are not
|
|
recognized as such by Cygwin.
|
|
noacl - Ignore ACLs and fake POSIX permissions.
|
|
nosuid - No suid files are allowed (currently unimplemented)
|
|
notexec - Treat all files below mount point as not executable.
|
|
override - Override immutable mount points.
|
|
posix=0 - Switch off case sensitivity for paths under this mount point.
|
|
posix=1 - Switch on case sensitivity for paths under this mount point
|
|
(default).
|
|
sparse - Switch on support for sparse files. This option only makes
|
|
sense on NTFS and then only if you really need sparse files.
|
|
text - Files default to CRLF text mode line endings.
|
|
</screen>
|
|
|
|
<para>For a more complete description of the mount options and the
|
|
<filename>/etc/fstab</filename> file, see <xref linkend="mount-table"
|
|
/>.</para>
|
|
|
|
<para>Note that all mount points added with <command>mount</command> are
|
|
user mount points. System mount points can only be specified in the
|
|
<filename>/etc/fstab</filename> file.</para>
|
|
|
|
<para>If you added mount points to <filename>/etc/fstab</filename> or
|
|
your <filename>/etc/fstab.d/<username></filename> file, you can
|
|
add these mount points to your current user session using the
|
|
<literal>-a/--all</literal> option, or by specifing the posix path
|
|
alone on the command line. As an example, consider you added a mount
|
|
point with the POSIX path <filename>/my/mount</filename>. You can add
|
|
this mount point with either one of the following two commands to your
|
|
current user session.</para>
|
|
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>mount /my/mount</userinput>
|
|
<prompt>$</prompt> <userinput>mount -a</userinput>
|
|
</screen>
|
|
|
|
<para>The first command just adds the <filename>/my/mount</filename>
|
|
mount point to your current session, the <command>mount -a</command>
|
|
adds all new mount points to your user session.</para>
|
|
|
|
<para>If you change a mount point to point to another native path, or if
|
|
you changed the flags of a mount point, you have to
|
|
<command>umount</command> the mount point first, before you can add it
|
|
again. Please note that all such added mount points are added as user
|
|
mount points, and that the rule that system mount points can't be
|
|
removed or replaced in a running session still applies.</para>
|
|
|
|
<para>To bind a POSIX path to another POSIX path, use the
|
|
<literal>bind</literal> mount flag.</para>
|
|
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>mount -o bind /var /usr/var</userinput>
|
|
</screen>
|
|
|
|
<para>This command makes the file hirarchy under
|
|
<filename>/var</filename> additionally available under
|
|
<filename>/usr/var</filename>.</para>
|
|
|
|
<para> The <literal>-m</literal> option causes the
|
|
<command>mount</command> utility to output the current mount table in a
|
|
series of fstab entries. You can save this output as a backup when
|
|
experimenting with the mount table. Copy the output to
|
|
<filename>/etc/fstab</filename> to restore the old state. It also makes
|
|
moving your settings to a different machine much easier.</para>
|
|
|
|
</refsect2>
|
|
|
|
<refsect2 id="utils-cygdrive">
|
|
<title>Cygdrive mount points</title>
|
|
|
|
<para>Whenever Cygwin cannot use any of the existing mounts to convert
|
|
from a particular Win32 path to a POSIX one, Cygwin will, instead,
|
|
convert to a POSIX path using a default mount point:
|
|
<filename>/cygdrive</filename>. For example, if Cygwin accesses
|
|
<filename>z:\foo</filename> and the z drive is not currently in the
|
|
mount table, then <filename>z:\</filename> will be accessible as
|
|
<filename>/cygdrive/z</filename>. The <command>mount</command> utility
|
|
can be used to change this default automount prefix through the use of
|
|
the "--change-cygdrive-prefix" option. In the following example, we
|
|
will set the automount prefix to <filename>/mnt</filename>:</para>
|
|
|
|
<example id="utils-cygdrive-ex">
|
|
<title>Changing the default prefix</title>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>mount --change-cygdrive-prefix /mnt</userinput>
|
|
</screen>
|
|
</example>
|
|
|
|
<para>Note that the cygdrive prefix can be set both per-user and
|
|
system-wide, and that as with all mounts, a user-specific mount takes
|
|
precedence over the system-wide setting. The <command>mount</command>
|
|
utility creates system-wide mounts by default if you do not specify a
|
|
type. You can always see the user and system cygdrive prefixes with the
|
|
<literal>-p</literal> option. Using the <literal>--options</literal>
|
|
flag with <literal>--change-cygdrive-prefix</literal> makes all new
|
|
automounted filesystems default to this set of options. For instance
|
|
(using the short form of the command line flags)</para>
|
|
|
|
<example id="utils-cygdrive-ex2">
|
|
<title>Changing the default prefix with specific mount options</title>
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>mount -c /mnt -o binary,noacl</userinput>
|
|
</screen>
|
|
</example>
|
|
|
|
|
|
</refsect2>
|
|
|
|
<refsect2 id="utils-limitations">
|
|
<title>Limitations</title>
|
|
|
|
<para>Limitations: there is a hard-coded limit of 64 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>
|
|
|
|
</refsect2>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="passwd">
|
|
<refmeta>
|
|
<refentrytitle>passwd</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>passwd</refname>
|
|
<refpurpose>Change USER's password or password attributes.</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
passwd [OPTION] [USER]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="passwd-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
User operations:
|
|
-l, --lock lock USER's account.
|
|
-u, --unlock unlock USER's account.
|
|
-c, --cannot-change USER can't change password.
|
|
-C, --can-change USER can change password.
|
|
-e, --never-expires USER's password never expires.
|
|
-E, --expires USER's password expires according to system's
|
|
password aging rule.
|
|
-p, --pwd-not-required no password required for USER.
|
|
-P, --pwd-required password is required for USER.
|
|
-R, --reg-store-pwd enter password to store it in the registry for
|
|
later usage by services to be able to switch
|
|
to this user context with network credentials.
|
|
|
|
System operations:
|
|
-i, --inactive NUM set NUM of days before inactive accounts are disabled
|
|
(inactive accounts are those with expired passwords).
|
|
-n, --minage MINDAYS set system minimum password age to MINDAYS days.
|
|
-x, --maxage MAXDAYS set system maximum password age to MAXDAYS days.
|
|
-L, --length LEN set system minimum password length to LEN.
|
|
|
|
Other options:
|
|
-d, --logonserver SERVER connect to SERVER (e.g. domain controller).
|
|
Usually not required.
|
|
-S, --status display password status for USER (locked, expired,
|
|
etc.) plus global system password settings.
|
|
-h, --help output usage information and exit.
|
|
-V, --version output version information and exit.
|
|
|
|
If no option is given, change USER's password. If no user name is given,
|
|
operate on current user. System operations must not be mixed with user
|
|
operations. Don't specify a USER when triggering a system operation.
|
|
|
|
Don't specify a user or any other option together with the -R option.
|
|
Non-Admin users can only store their password if cygserver is running.
|
|
Note that storing even obfuscated passwords in the registry is not overly
|
|
secure. Use this feature only if the machine is adequately locked down.
|
|
Don't use this feature if you don't need network access within a remote
|
|
session. You can delete your stored password by using `passwd -R' and
|
|
specifying an empty password.
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="passwd-desc">
|
|
<title>Description</title>
|
|
<para> <command>passwd</command> changes passwords for user accounts. A
|
|
normal user may only change the password for their own account, but
|
|
administrators may change passwords on any account.
|
|
<command>passwd</command> also changes account information, such as
|
|
password expiry dates and intervals.</para>
|
|
|
|
<para>For password changes, the user is first prompted for their old
|
|
password, if one is present. This password is then encrypted and compared
|
|
against the stored password. The user has only one chance to enter the
|
|
correct password. The administrators are permitted to bypass this step so
|
|
that forgotten passwords may be changed.</para>
|
|
|
|
<para>The user is then prompted for a replacement password.
|
|
<command>passwd</command> will prompt twice for this replacement and
|
|
compare the second entry against the first. Both entries are required to
|
|
match in order for the password to be changed.</para>
|
|
|
|
<para>After the password has been entered, password aging information is
|
|
checked to see if the user is permitted to change their password at this
|
|
time. If not, <command>passwd</command> refuses to change the password
|
|
and exits.</para>
|
|
|
|
<para> To get current password status information, use the
|
|
<literal>-S</literal> option. Administrators can use
|
|
<command>passwd</command> to perform several account maintenance
|
|
functions (users may perform some of these functions on their own
|
|
accounts). Accounts may be locked with the <literal>-l</literal> flag and
|
|
unlocked with the <literal>-u</literal> flag. Similarly,
|
|
<literal>-c</literal> disables a user's ability to change passwords, and
|
|
<literal>-C</literal> allows a user to change passwords. For password
|
|
expiry, the <literal>-e</literal> option disables expiration, while the
|
|
<literal>-E</literal> option causes the password to expire according to
|
|
the system's normal aging rules. Use <literal>-p</literal> to disable the
|
|
password requirement for a user, or <literal>-P</literal> to require a
|
|
password. </para>
|
|
|
|
<para>Administrators can also use <command>passwd</command> to change
|
|
system-wide password expiry and length requirements with the
|
|
<literal>-i</literal>, <literal>-n</literal>, <literal>-x</literal>, and
|
|
<literal>-L</literal> options. The <literal>-i</literal> option is used
|
|
to disable an account after the password has been expired for a number of
|
|
days. After a user account has had an expired password for
|
|
<emphasis>NUM</emphasis> days, the user may no longer sign on to the
|
|
account. The <literal>-n</literal> option is used to set the minimum
|
|
number of days before a password may be changed. The user will not be
|
|
permitted to change the password until <emphasis>MINDAYS</emphasis> days
|
|
have elapsed. The <literal>-x</literal> option is used to set the maximum
|
|
number of days a password remains valid. After
|
|
<emphasis>MAXDAYS</emphasis> days, the password is required to be
|
|
changed. Allowed values for the above options are 0 to 999. The
|
|
<literal>-L</literal> option sets the minimum length of allowed passwords
|
|
for users who don't belong to the administrators group to
|
|
<emphasis>LEN</emphasis> characters. Allowed values for the minimum
|
|
password length are 0 to 14. In any of the above cases, a value of 0
|
|
means `no restrictions'.</para>
|
|
|
|
<para> All operations affecting the current user are by default run against
|
|
the logon server of the current user (taken from the environment variable
|
|
<envar>LOGONSERVER</envar>. When password or account information of other
|
|
users should be changed, the logon server is evaluated automatically.
|
|
In rare cases, it might be necessary to switch to another domain
|
|
controller to perform the action. In this case, use the
|
|
<literal>-d</literal> option to specify the machine to run the command
|
|
against. Note that the current user must have account operator permissions
|
|
to perform user account changes in a domain. </para>
|
|
|
|
<para>Users can use the <command>passwd -R</command> to enter a password
|
|
which then gets stored in a special area of the registry on the local
|
|
system, which is also used by Windows to store passwords of accounts
|
|
running Windows services. When a privileged Cygwin application calls the
|
|
<command>set{e}uid(user_id)</command> system call, Cygwin checks if a
|
|
password for that user has been stored in this registry area. If so, it
|
|
uses this password to switch to this user account using that password.
|
|
This allows you to logon through, for instance, <command>ssh</command>
|
|
with public key authentication and get a full qualified user token with
|
|
all credentials for network access. However, the method has some
|
|
drawbacks security-wise. This is explained in more detail in <xref
|
|
linkend="ntsec"/>.</para>
|
|
|
|
<para>Please note that storing passwords in that registry area is a
|
|
privileged operation which only administrative accounts are allowed to
|
|
do. Administrators can enter the password for other user accounts into
|
|
the registry by specifying the username on the commandline. If normal,
|
|
non-admin users should be allowed to enter their passwords using
|
|
<command>passwd -R</command>, it's required to run
|
|
<command>cygserver</command> as a service under the LocalSystem account
|
|
before running <command>passwd -R</command>. This only affects storing
|
|
passwords. Using passwords in privileged processes does not require
|
|
<command>cygserver</command> to run.</para>
|
|
|
|
<para>Limitations: Users may not be able to change their password on some
|
|
systems.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="pldd">
|
|
<refmeta>
|
|
<refentrytitle>pldd</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>pldd</refname>
|
|
<refpurpose>List dynamic shared objects loaded into a process</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
pldd [OPTION...] PID
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="pldd-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-?, --help Give this help list
|
|
--usage Give a short usage message
|
|
-V, --version Print program version
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="pldd-desc">
|
|
<title>Description</title>
|
|
<para><command>pldd</command> prints the shared libraries (DLLs) loaded by
|
|
the process with the given PID.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ps">
|
|
<refmeta>
|
|
<refentrytitle>ps</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>ps</refname>
|
|
<refpurpose>Report process status</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
ps [-aefls] [-u UID]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="ps-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-a, --all show processes of all users
|
|
-e, --everyone show processes of all users
|
|
-f, --full show process uids, ppids
|
|
-h, --help output usage information and exit
|
|
-l, --long show process uids, ppids, pgids, winpids
|
|
-p, --process show information for specified PID
|
|
-s, --summary show process summary
|
|
-u, --user list processes owned by UID
|
|
-V, --version output version information and exit
|
|
-W, --windows show windows as well as cygwin processes
|
|
With no options, ps outputs the long format by default
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="ps-desc">
|
|
<title>Description</title>
|
|
<para>The <command>ps</command> program gives the status of all the Cygwin
|
|
processes running on the system (ps = "process status"). Due to the
|
|
limitations of simulating a POSIX environment under Windows, there is
|
|
little information to give. </para>
|
|
|
|
<para> The PID column is the process ID you need to give to the
|
|
<command>kill</command> command. The PPID is the parent process ID, and
|
|
PGID is the process group ID. The WINPID column is the process ID
|
|
displayed by NT's Task Manager program. The TTY column gives which
|
|
pseudo-terminal a process is running on, or a <literal>'?'</literal> for
|
|
services. The UID column shows which user owns each process. STIME is the
|
|
time the process was started, and COMMAND gives the name of the program
|
|
running. Listings may also have a status flag in column zero;
|
|
<literal>S</literal> means stopped or suspended (in other words, in the
|
|
background), <literal>I</literal> means waiting for input or interactive
|
|
(foreground), and <literal>O</literal> means waiting to output. </para>
|
|
|
|
<para> By default, <command>ps</command> will only show processes owned by
|
|
the current user. With either the <literal>-a</literal> or
|
|
<literal>-e</literal> option, all user's processes (and system processes)
|
|
are listed. There are historical UNIX reasons for the synonomous options,
|
|
which are functionally identical. The <literal>-f</literal> option
|
|
outputs a "full" listing with usernames for UIDs. The
|
|
<literal>-l</literal> option is the default display mode, showing a
|
|
"long" listing with all the above columns. The other display option is
|
|
<literal>-s</literal>, which outputs a shorter listing of just PID, TTY,
|
|
STIME, and COMMAND. The <literal>-u</literal> option allows you to show
|
|
only processes owned by a specific user. The <literal>-p</literal> option
|
|
allows you to show information for only the process with the specified
|
|
PID. The <literal>-W</literal> option causes <command>ps</command> show
|
|
non-Cygwin Windows processes as well as Cygwin processes. The WINPID is
|
|
also the PID, and they can be killed with the Cygwin
|
|
<command>kill</command> command's <literal>-f</literal> option. </para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="regtool">
|
|
<refmeta>
|
|
<refentrytitle>regtool</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>regtool</refname>
|
|
<refpurpose>View or edit the Windows registry</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="regtool-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
Actions:
|
|
|
|
add KEY\SUBKEY add new SUBKEY
|
|
check KEY exit 0 if KEY exists, 1 if not
|
|
get KEY\VALUE prints VALUE to stdout
|
|
list KEY list SUBKEYs and VALUEs
|
|
remove KEY remove KEY
|
|
set KEY\VALUE [data ...] set VALUE
|
|
unset KEY\VALUE removes VALUE from KEY
|
|
load KEY\SUBKEY PATH load hive from PATH into new SUBKEY
|
|
unload KEY\SUBKEY unload hive and remove SUBKEY
|
|
save KEY\SUBKEY PATH save SUBKEY into new file PATH
|
|
restore KEY\SUBKEY PATH restore SUBKEY from file PATH
|
|
|
|
Options for 'list' Action:
|
|
|
|
-k, --keys print only KEYs
|
|
-l, --list print only VALUEs
|
|
-p, --postfix like ls -p, appends '\' postfix to KEY names
|
|
|
|
Options for 'get' Action:
|
|
|
|
-b, --binary print REG_BINARY data as hex bytes
|
|
-n, --none print data as stream of bytes as stored in registry
|
|
-x, --hex print numerical data as hex numbers
|
|
|
|
Options for 'set' Action:
|
|
|
|
-b, --binary set type to REG_BINARY (hex args or '-')
|
|
-D, --dword-be set type to REG_DWORD_BIG_ENDIAN
|
|
-e, --expand-string set type to REG_EXPAND_SZ
|
|
-i, --integer set type to REG_DWORD
|
|
-m, --multi-string set type to REG_MULTI_SZ
|
|
-n, --none set type to REG_NONE
|
|
-Q, --qword set type to REG_QWORD
|
|
-s, --string set type to REG_SZ
|
|
|
|
Options for 'set' and 'unset' Actions:
|
|
|
|
-K<c>, --key-separator[=]<c> set key separator to <c> instead of '\'
|
|
|
|
Options for 'restore' action:
|
|
|
|
-f, --force restore even if open handles exist at or beneath the location
|
|
in the registry hierarchy to which KEY\SUBKEY points
|
|
|
|
Other Options:
|
|
|
|
-h, --help output usage information and exit
|
|
-q, --quiet no error output, just nonzero return if KEY/VALUE missing
|
|
-v, --verbose verbose output, including VALUE contents when applicable
|
|
-w, --wow64 access 64 bit registry view (ignored on 32 bit Windows)
|
|
-W, --wow32 access 32 bit registry view (ignored on 32 bit Windows)
|
|
-V, --version output version information and exit
|
|
|
|
KEY is in the format [host]\prefix\KEY\KEY\VALUE, where host is optional
|
|
remote host in either \\hostname or hostname: format and prefix is any of:
|
|
root HKCR HKEY_CLASSES_ROOT (local only)
|
|
config HKCC HKEY_CURRENT_CONFIG (local only)
|
|
user HKCU HKEY_CURRENT_USER (local only)
|
|
machine HKLM HKEY_LOCAL_MACHINE
|
|
users HKU HKEY_USERS
|
|
|
|
You can use forward slash ('/') as a separator instead of backslash, in
|
|
that case backslash is treated as escape character
|
|
Example: regtool get '\user\software\Microsoft\Clock\iFormat'
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="regtool-desc">
|
|
<title>Description</title>
|
|
<para>The <command>regtool</command> program allows shell scripts to access
|
|
and modify the Windows registry. Note that modifying the Windows registry
|
|
is dangerous, and carelessness here can result in an unusable system. Be
|
|
careful.</para>
|
|
|
|
<para>The <literal>-v</literal> option means "verbose". For most commands,
|
|
this causes additional or lengthier messages to be printed. Conversely,
|
|
the <literal>-q</literal> option supresses error messages, so you can use
|
|
the exit status of the program to detect if a key exists or not (for
|
|
example).</para>
|
|
|
|
<para>The <literal>-w</literal> option allows you to access the 64 bit view
|
|
of the registry. Several subkeys exist in a 32 bit and a 64 bit version
|
|
when running on Windows 64. Since Cygwin is running in 32 bit mode, it
|
|
only has access to the 32 bit view of these registry keys. When using the
|
|
<literal>-w</literal> switch, the 64 bit view is used and
|
|
<command>regtool</command> can access the entire registry. This option is
|
|
simply ignored when running on 32 bit Windows versions. </para>
|
|
|
|
<para>The <literal>-W</literal> option allows you to access the 32 bit view
|
|
on the registry. The purpose of this option is mainly for symmetry. It
|
|
permits creation of OS agnostic scripts which would also work in a
|
|
hypothetical 64 bit version of Cygwin.</para>
|
|
|
|
<para>You must provide <command>regtool</command> with an
|
|
<emphasis>action</emphasis> following options (if any). Currently, the
|
|
action must be <literal>add</literal>, <literal>set</literal>,
|
|
<literal>check</literal>, <literal>get</literal>,
|
|
<literal>list</literal>, <literal>remove</literal>,
|
|
<literal>set</literal>, or <literal>unset</literal>. </para>
|
|
|
|
<para>The <literal>add</literal> action adds a new key. The
|
|
<literal>check</literal> action checks to see if a key exists (the exit
|
|
code of the program is zero if it does, nonzero if it does not). The
|
|
<literal>get</literal> action gets the value of a key, and prints it (and
|
|
nothing else) to stdout. Note: if the value doesn't exist, an error
|
|
message is printed and the program returns a non-zero exit code. If you
|
|
give <literal>-q</literal>, it doesn't print the message but does return
|
|
the non-zero exit code.</para>
|
|
|
|
<para> The <literal>list</literal> action lists the subkeys and values
|
|
belonging to the given key. With <literal>list</literal>, the
|
|
<literal>-k</literal> option instructs <command>regtool</command> to
|
|
print only KEYs, and the <literal>-l</literal> option to print only
|
|
VALUEs. The <literal>-p</literal> option postfixes a
|
|
<literal>'/'</literal> to each KEY, but leave VALUEs with no postfix. The
|
|
<literal>remove</literal> action removes a key. Note that you may need to
|
|
remove everything in the key before you may remove it, but don't rely on
|
|
this stopping you from accidentally removing too much. </para>
|
|
|
|
<para>The <literal>get</literal> action prints a value within a key. With
|
|
the <literal>-b</literal> option, data is printed as hex bytes.
|
|
<literal>-n</literal> allows to print the data as a typeless stream of
|
|
bytes. Integer values (REG_DWORD, REG_QWORD) are usually printed as
|
|
decimal values. The <literal>-x</literal> option allows to print the
|
|
numbers as hexadecimal values.</para>
|
|
|
|
<para>The <literal>set</literal> action sets a value within a key.
|
|
<literal>-b</literal> means it's binary data (REG_BINARY). The binary
|
|
values are specified as hex bytes in the argument list. If the argument
|
|
is <literal>'-'</literal>, binary data is read from stdin instead.
|
|
<literal>-d</literal> or <literal>-i</literal> means the value is a 32
|
|
bit integer value (REG_DWORD). <literal>-D</literal> means the value is a
|
|
32 bit integer value in Big Endian representation (REG_DWORD_BIG_ENDIAN).
|
|
<literal>-Q</literal> means the value is a 64 bit integer value
|
|
(REG_QWORD). <literal>-s</literal> means the value is a string (REG_SZ).
|
|
<literal>-e</literal> means it's an expanding string (REG_EXPAND_SZ) that
|
|
contains embedded environment variables. <literal>-m</literal> means it's
|
|
a multi-string (REG_MULTI_SZ). If you don't specify one of these,
|
|
<command>regtool</command> tries to guess the type based on the value you
|
|
give. If it looks like a number, it's a DWORD, unless it's value doesn't
|
|
fit into 32 bit, in which case it's a QWORD. If it starts with a percent,
|
|
it's an expanding string. If you give multiple values, it's a
|
|
multi-string. Else, it's a regular string.</para>
|
|
|
|
<para>The <literal>unset</literal> action removes a value from a
|
|
key.</para>
|
|
|
|
<para>The <literal>load</literal> action adds a new subkey and loads the
|
|
contents of a registry hive into it. The parent key must be
|
|
HKEY_LOCAL_MACHINE or HKEY_USERS. The <literal>unload</literal> action
|
|
unloads the file and removes the subkey. </para>
|
|
|
|
<para>The <literal>save</literal> action saves a subkey into a registry
|
|
file. Ideally you append the suffix <filename>.reg</filename> to the file
|
|
so it gets automatically recognized as registry file by
|
|
<command>Windows Explorer</command>.</para>
|
|
|
|
<para>The <literal>restore</literal> action restores a registry subkey
|
|
from a file saved via the aforementioned <literal>save</literal> action.
|
|
</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>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="setfacl">
|
|
<refmeta>
|
|
<refentrytitle>setfacl</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>setfacl</refname>
|
|
<refpurpose>Modify file and directory access control lists (ACLs)</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
setfacl [-n] {-f ACL_FILE | -s acl_entries} FILE...
|
|
setfacl [-n] {[-bk]|[-x acl_entries] [-m acl_entries]} FILE...
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="setfacl-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-b, --remove-all remove all extended ACL entries\n"
|
|
-x, --delete delete one or more specified ACL entries\n"
|
|
-f, --set-file set ACL entries for FILE to ACL entries read\n"
|
|
from ACL_FILE\n"
|
|
-k, --remove-default remove all default ACL entries\n"
|
|
-m, --modify modify one or more specified ACL entries\n"
|
|
-n, --no-mask don't recalculate the effective rights mask\n"
|
|
--mask do recalculate the effective rights mask\n"
|
|
-s, --set set specified ACL entries on FILE\n"
|
|
-V, --version print version and exit\n"
|
|
-h, --help this help text\n"
|
|
|
|
At least one of (-b, -x, -f, -k, -m, -s) must be specified\n"
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="setfacl-desc">
|
|
<title>Description</title>
|
|
<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
|
|
<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>-b</literal>,<literal>--remove-all</literal> Remove all
|
|
extended ACL entries. The base ACL entries of the owner, group and
|
|
others are retained. This option can be combined with the
|
|
<literal>-k</literal>,<literal>--remove-default</literal> option
|
|
to delete all non-standard POSIX permissions.</para>
|
|
|
|
<para> <literal>-x</literal>,<literal>--delete</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[:]
|
|
m[ask][:]
|
|
d[efault]:u[ser][:uid]
|
|
d[efault]:g[roup][:gid]
|
|
d[efault]:m[ask][:]
|
|
d[efault]:o[ther][:]
|
|
</screen> </para>
|
|
|
|
<para> <literal>-f</literal>,<literal>--set-file</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>-k</literal>,<literal>--remove-default</literal> Remove all
|
|
default ACL entries. If no default ACL entries exist, no warnings are
|
|
issued. This option can be combined with the
|
|
<literal>-b</literal>,<literal>--remove-all</literal> option
|
|
to delete all non-standard POSIX permissions.</para>
|
|
|
|
<para> <literal>-m</literal>,<literal>--modify</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>-n</literal>,<literal>--no-mask</literal> Valid in
|
|
conjunction with -m. Do not recalculate the effective rights mask.
|
|
The default behavior of setfacl is to recalculate the ACL mask entry,
|
|
unless a mask entry was explicitly given. The mask entry is set to
|
|
the union of all permissions of the owning group, and all named user
|
|
and group entries. (These are exactly the entries affected by the
|
|
mask entry). </para>
|
|
|
|
<para> <literal>--mask</literal> Valid in conjunction with -m. Do
|
|
recalculate the effective rights mask, even if an ACL mask entry was
|
|
explicitly given. (See the -n option.) </para>
|
|
|
|
<para> <literal>-s</literal>,<literal>--set</literal> Like
|
|
<literal>-f</literal>, but set the file's ACL with Acl_entries
|
|
specified in a comma-separated list on the command line. </para>
|
|
|
|
<para> While the <literal>-x</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>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="setmetamode">
|
|
<refmeta>
|
|
<refentrytitle>setmetamode</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>setmetamode</refname>
|
|
<refpurpose>Get or set keyboard meta mode</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
setmetamode [metabit|escprefix]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="setmetamode-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
Without argument, it shows the current meta key mode.
|
|
|
|
metabit|meta|bit The meta key sets the top bit of the character.
|
|
escprefix|esc|prefix The meta key sends an escape prefix.
|
|
|
|
Other options:
|
|
|
|
-h, --help This text
|
|
-V, --version Print program version and exit
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="setmetamode-desc">
|
|
<title>Description</title>
|
|
<para><command>setmetamode</command> can be used to determine and set the
|
|
key code sent by the meta (aka <literal>Alt</literal>) key.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="ssp">
|
|
<refmeta>
|
|
<refentrytitle>ssp</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>ssp</refname>
|
|
<refpurpose>Single-step profile COMMAND</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
ssp [options] low_pc high_pc command...
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="ssp-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-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>
|
|
</refsect1>
|
|
|
|
<refsect1 id="ssp-desc">
|
|
<title>Description</title>
|
|
<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>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="strace">
|
|
<refmeta>
|
|
<refentrytitle>strace</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>strace</refname>
|
|
<refpurpose>Trace system calls and signals</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
strace [OPTIONS] <command-line>
|
|
strace [OPTIONS] -p <pid>
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="strace-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-b, --buffer-size=SIZE set size of output file buffer
|
|
-d, --no-delta don't display the delta-t microsecond timestamp
|
|
-e, --events log all Windows DEBUG_EVENTS (toggle - default true)
|
|
-f, --trace-children trace child processes (toggle - default true)
|
|
-h, --help output usage information and exit
|
|
-m, --mask=MASK set message filter mask
|
|
-n, --crack-error-numbers output descriptive text instead of error
|
|
numbers for Windows errors
|
|
-o, --output=FILENAME set output file to FILENAME
|
|
-p, --pid=n attach to executing program with cygwin pid n
|
|
-q, --quiet toggle "quiet" flag. Defaults to on if "-p",
|
|
off otherwise.
|
|
-S, --flush-period=PERIOD flush buffered strace output every PERIOD secs
|
|
-t, --timestamp use an absolute hh:mm:ss timestamp insted of
|
|
the default microsecond timestamp. Implies -d
|
|
-T, --toggle toggle tracing in a process already being
|
|
traced. Requires -p <pid>
|
|
-u, --usecs toggle printing of microseconds timestamp
|
|
-V, --version output version information and exit
|
|
-w, --new-window spawn program under test in a new window
|
|
|
|
MASK can be any combination of the following mnemonics and/or hex values
|
|
(0x is optional). Combine masks with '+' or ',' like so:
|
|
|
|
--mask=wm+system,malloc+0x00800
|
|
|
|
Mnemonic Hex Corresponding Def Description
|
|
=========================================================================
|
|
all 0x000001 (_STRACE_ALL) All strace messages.
|
|
flush 0x000002 (_STRACE_FLUSH) Flush output buffer after each message.
|
|
inherit 0x000004 (_STRACE_INHERIT) Children inherit mask from parent.
|
|
uhoh 0x000008 (_STRACE_UHOH) Unusual or weird phenomenon.
|
|
syscall 0x000010 (_STRACE_SYSCALL) System calls.
|
|
startup 0x000020 (_STRACE_STARTUP) argc/envp printout at startup.
|
|
debug 0x000040 (_STRACE_DEBUG) Info to help debugging.
|
|
paranoid 0x000080 (_STRACE_PARANOID) Paranoid info.
|
|
termios 0x000100 (_STRACE_TERMIOS) Info for debugging termios stuff.
|
|
select 0x000200 (_STRACE_SELECT) Info on ugly select internals.
|
|
wm 0x000400 (_STRACE_WM) Trace Windows msgs (enable _strace_wm).
|
|
sigp 0x000800 (_STRACE_SIGP) Trace signal and process handling.
|
|
minimal 0x001000 (_STRACE_MINIMAL) Very minimal strace output.
|
|
pthread 0x002000 (_STRACE_PTHREAD) Pthread calls.
|
|
exitdump 0x004000 (_STRACE_EXITDUMP) Dump strace cache on exit.
|
|
system 0x008000 (_STRACE_SYSTEM) Serious error; goes to console and log.
|
|
nomutex 0x010000 (_STRACE_NOMUTEX) Don't use mutex for synchronization.
|
|
malloc 0x020000 (_STRACE_MALLOC) Trace malloc calls.
|
|
thread 0x040000 (_STRACE_THREAD) Thread-locking calls.
|
|
special 0x100000 (_STRACE_SPECIAL) Special debugging printfs for
|
|
non-checked-in code
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="strace-desc">
|
|
<title>Description</title>
|
|
<para>The <command>strace</command> program executes a program, and
|
|
optionally the children of the program, reporting any Cygwin DLL output
|
|
from the program(s) to stdout, or to a file with the
|
|
<literal>-o</literal> option. With the <literal>-w</literal> option, you
|
|
can start an strace session in a new window, for example:
|
|
<screen>
|
|
$ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' &
|
|
</screen>
|
|
This is particularly useful for <command>strace</command> sessions that
|
|
take a long time to complete. </para>
|
|
|
|
<para> Note that <command>strace</command> is a standalone Windows program
|
|
and so does not rely on the Cygwin DLL itself (you can verify this with
|
|
<command>cygcheck</command>). As a result it does not understand
|
|
symlinks. This program is mainly useful for debugging the Cygwin DLL
|
|
itself.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="tzset">
|
|
<refmeta>
|
|
<refentrytitle>tzset</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>tzset</refname>
|
|
<refpurpose>Print POSIX-compatible timezone ID from current Windows timezone setting</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
tzset [OPTION]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="tzset-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
Options:
|
|
-h, --help output usage information and exit.
|
|
-V, --version output version information and exit.
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="tzset-desc">
|
|
<title>Description</title>
|
|
Use tzset to set your TZ variable. In POSIX-compatible shells like bash,
|
|
dash, mksh, or zsh:
|
|
<screen>
|
|
export TZ=$(tzset)
|
|
</screen>
|
|
In csh-compatible shells like tcsh:
|
|
<screen>
|
|
setenv TZ `tzset`
|
|
</screen>
|
|
|
|
<para>The <command>tzset</command> tool reads the current timezone from
|
|
Windows and generates a POSIX-compatible timezone information for the TZ
|
|
environment variable from that information. That's all there is to it.
|
|
For the way how to use it, see the above usage information.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="umount">
|
|
<refmeta>
|
|
<refentrytitle>umount</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo class="manual">Cygwin Utilities</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>umount</refname>
|
|
<refpurpose>Unmount filesystems</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv>
|
|
<screen>
|
|
umount [OPTION] [<posixpath>]
|
|
</screen>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id="umount-options">
|
|
<title>Options</title>
|
|
<screen>
|
|
-h, --help output usage information and exit
|
|
-U, --remove-user-mounts remove all user mounts
|
|
-V, --version output version information and exit
|
|
</screen>
|
|
</refsect1>
|
|
|
|
<refsect1 id="umount-desc">
|
|
<title>Description</title>
|
|
<para>The <command>umount</command> program removes mounts from the mount
|
|
table in the current session. If you specify a POSIX path that
|
|
corresponds to a current mount point, <command>umount</command> will
|
|
remove it from the current mount table. Note that you can only remove
|
|
user mount points. The <literal>-U</literal> flag may be used to specify
|
|
removing all user mount points from the current user session.</para>
|
|
|
|
<para>See <xref linkend="mount-table"/> for more information on the mount
|
|
table.</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</sect1>
|