| <?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, --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>--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> |
