1 <sect1 id="using-utils"><title>Cygwin Utilities</title>
3 <para>Cygwin comes with a number of command-line utilities that are
4 used to manage the UNIX emulation portion of the Cygwin environment.
5 While many of these reflect their UNIX counterparts, each was written
6 specifically for Cygwin. You may use the long or short option names
7 interchangeably; for example, <literal>--help</literal> and
8 <literal>-h</literal> function identically. All of the Cygwin
9 command-line utilities support the <literal>--help</literal> and
10 <literal>--version</literal> options.
13 <sect2 id="cygcheck"><title>cygcheck</title>
16 Usage: cygcheck [-v] [-h] PROGRAM
17 cygcheck -c [-d] [PACKAGE]
18 cygcheck -s [-r] [-v] [-h]
20 cygcheck -f FILE [FILE]...
21 cygcheck -l [PACKAGE]...
23 cygcheck --delete-orphaned-installation-keys
24 cygcheck --enable-unique-object-names Cygwin-DLL
25 cygcheck --disable-unique-object-names Cygwin-DLL
26 cygcheck --show-unique-object-names Cygwin-DLL
28 List system information, check installed packages, or query package database.
30 At least one command option or a PROGRAM is required, as shown above.
32 PROGRAM list library (DLL) dependencies of PROGRAM
33 -c, --check-setup show installed version of PACKAGE and verify integrity
34 (or for all installed packages if none specified)
35 -d, --dump-only just list packages, do not verify (with -c)
36 -s, --sysinfo produce diagnostic system information (implies -c -d)
37 -r, --registry also scan registry for Cygwin settings (with -s)
38 -k, --keycheck perform a keyboard check session (must be run from a
39 plain console only, not from a pty/rxvt/xterm)
40 -f, --find-package find the package to which FILE belongs
41 -l, --list-package list contents of PACKAGE (or all packages if none given)
42 -p, --package-query search for REGEXP in the entire cygwin.com package
43 repository (requires internet connectivity)
44 --delete-orphaned-installation-keys
45 Delete installation keys of old, now unused
46 installations from the registry. Requires the right
47 to change the registry.
48 --enable-unique-object-names Cygwin-DLL
49 --disable-unique-object-names Cygwin-DLL
50 --show-unique-object-names Cygwin-DLL
51 Enable, disable, or show the setting of the
52 \"unique object names\" setting in the Cygwin DLL
53 given as argument to this option. The DLL path must
54 be given as valid Windows(!) path.
55 See the users guide for more information.
56 If you don't know what this means, don't change it.
57 -v, --verbose produce more verbose output
58 -h, --help annotate output with explanatory comments when given
59 with another command, otherwise print this help
60 -V, --version print the version of cygcheck and exit
62 Note: -c, -f, and -l only report on packages that are currently installed. To
63 search all official Cygwin packages use -p instead. The -p REGEXP matches
64 package names, descriptions, and names of files/paths within all packages.
68 The <command>cygcheck</command> program is a diagnostic utility for
69 dealing with Cygwin programs. If you are familiar with
70 <command>dpkg</command> or <command>rpm</command>,
71 <command>cygcheck</command> is similar in many ways. (The major difference
72 is that <command>setup.exe</command> handles installing and uninstalling
73 packages; see <xref linkend="internet-setup"></xref> for more information.)
76 The <literal>-c</literal> option checks the version and status of
77 installed Cygwin packages. If you specify one or more package names,
78 <command>cygcheck</command> will limit its output to those packages,
79 or with no arguments it lists all packages. A package will be marked
80 <literal>Incomplete</literal> if files originally installed are no longer
81 present. The best thing to do in that situation is reinstall the package
82 with <command>setup.exe</command>. To see which files are missing, use the
83 <literal>-v</literal> option. If you do not need to know the status
84 of each package and want <command>cygcheck</command> to run faster, add the
85 <literal>-d</literal> option and <command>cygcheck</command> will only
86 output the name and version for each package.
89 If you list one or more programs on the command line,
90 <command>cygcheck</command> will diagnose the runtime environment of that
91 program or programs, providing the names of DLL files on which the program
92 depends. If you specify the <literal>-s</literal> option,
93 <command>cygcheck</command> will give general system information. If you
94 list one or more programs on the command line and specify
95 <literal>-s</literal>, <command>cygcheck</command> will report on
98 The <literal>-f</literal> option helps you to track down which package a
99 file came from, and <literal>-l</literal> lists all files in a package.
100 For example, to find out about <filename>/usr/bin/less</filename> and its
102 <example id="utils-cygcheck-ex"><title>Example <command>cygcheck</command> usage</title>
104 $ cygcheck -f /usr/bin/less
109 /usr/bin/lessecho.exe
112 /usr/man/man1/lesskey.1
117 <para>The <literal>-h</literal> option prints additional helpful
118 messages in the report, at the beginning of each section. It also
119 adds table column headings. While this is useful information, it also
120 adds some to the size of the report, so if you want a compact report
121 or if you know what everything is already, just leave this out.</para>
123 <para>The <literal>-v</literal> option causes the output to be more
124 verbose. What this means is that additional information will be
125 reported which is usually not interesting, such as the internal
126 version numbers of DLLs, additional information about recursive DLL
127 usage, and if a file in one directory in the PATH also occurs in other
128 directories on the PATH. </para>
130 <para>The <literal>-r</literal> option causes
131 <command>cygcheck</command> to search your registry for information
132 that is relevent to Cygwin programs. These registry entries are the
133 ones that have "Cygwin" in the name. If you are paranoid about
134 privacy, you may remove information from this report, but please keep
135 in mind that doing so makes it harder to diagnose your problems.</para>
137 <para>In contrast to the other options that search the packages that are
138 installed on your local system, the <literal>-p</literal> option can be used
139 to search the entire official Cygwin package repository. It takes as argument
140 a Perl-compatible regular expression which is used to match package names,
141 package descriptions, and path/filenames of the contents of packages. This
142 feature requires an active internet connection, since it must query the
143 <literal>cygwin.com</literal> web site. In fact, it is equalivant to the
144 search that is available on the <ulink url="http://cygwin.com/packages/">Cygwin
145 package listing</ulink> page.</para>
147 <para>For example, perhaps you are getting an error because you are missing a
148 certain DLL and you want to know which package includes that file:
149 <example id="utils-search-ex"><title>Searching all packages for a file</title>
151 $ cygcheck -p 'cygintl-2\.dll'
152 Found 1 matches for 'cygintl-2\.dll'.
154 libintl2-0.12.1-3 GNU Internationalization runtime library
156 $ cygcheck -p 'libexpat.*\.a'
157 Found 2 matches for 'libexpat.*\.a'.
159 expat-1.95.7-1 XML parser library written in C
160 expat-1.95.8-1 XML parser library written in C
162 $ cygcheck -p '/ls\.exe'
163 Found 2 matches for '/ls\.exe'.
165 coreutils-5.2.1-5 GNU core utilities (includes fileutils, sh-utils and textutils)
166 coreutils-5.3.0-6 GNU core utilities (includes fileutils, sh-utils and textutils)
171 <para>Note that this option takes a regular expression, not a glob or wildcard.
172 This means that you need to use <literal>.*</literal> if you want something
173 similar to the wildcard <literal>*</literal> commonly used in filename globbing.
174 Similarly, to match the period character you should use <literal>\.</literal>
175 since the <literal>.</literal> character in a regexp is a metacharacter that
176 will match any character. Also be aware that the characters such as
177 <literal>\</literal> and <literal>*</literal> are shell metacharacters, so
178 they must be either escaped or quoted, as in the example above.</para>
180 <para>The third example above illustrates that if you want to match a whole
181 filename, you should include the <literal>/</literal> path seperator. In the
182 given example this ensures that filenames that happen to end in
183 <literal>ls.exe</literal> such as <literal>ncftpls.exe</literal> are not shown.
184 Note that this use does not mean "look for packages with <literal>ls</literal>
185 in the root directory," since the <literal>/</literal> can match anywhere in the
186 path. It's just there to anchor the match so that it matches a full
189 <para>By default the matching is case-sensitive. To get a case insensitive
190 match, begin your regexp with <literal>(?i)</literal> which is a PCRE-specific
191 feature. For complete documentation on Perl-compatible regular expression
192 syntax and options, read the <command>perlre</command> manpage, or one of many
193 websites such as <literal>perldoc.com</literal> that document the Perl
196 <para>The <command>cygcheck</command> program should be used to send
197 information about your system for troubleshooting when requested.
198 When asked to run this command save the output so that you can email it,
202 <prompt>$</prompt> <userinput>cygcheck -s -v -r -h > cygcheck_output.txt</userinput>
206 Each Cygwin DLL stores its path and installation key in the registry.
207 This allows troubleshooting of problems which could be a result of having
208 multiple concurrent Cygwin installations. However, if you're experimenting
209 a lot with different Cygwin installation paths, your registry could
210 accumulate a lot of old Cygwin installation entries for which the
211 installation doesn't exist anymore. To get rid of these orphaned registry
212 entries, use the <command>cygcheck --delete-orphaned-installation-keys</command>
216 Each Cygwin DLL generates a key value from its installation path. This
217 value is not only stored in the registry, it's also used to generate
218 global object names used for interprocess communication. This keeps
219 different Cygwin installations separate. Processes running under a
220 Cygwin DLL installed in C:\cygwin don't see processes running under a
221 Cygwin DLL installed in C:\Program Files\cygwin. This allows
222 running multiple versions of Cygwin DLLs without these versions to
223 interfere with each other, or to run small third-party installations
224 for a specific purpose independently from a Cygwin net distribution.
228 For debugging purposes it could be desired that the various Cygwin DLLs
229 use the same key, independently from their installation paths. If the
230 DLLs have different versions, trying to run processes under these DLLs
231 concurrently will result in error messages like this one:</para>
234 *** shared version mismatch detected - 0x8A88009C/0x75BE0074.
235 This problem is probably due to using incompatible versions of the cygwin DLL.
236 Search for cygwin1.dll using the Windows Start->Find/Search facility
237 and delete all but the most recent version. The most recent version *should*
238 reside in x:\\cygwin\\bin, where 'x' is the drive on which you have
239 installed the cygwin distribution. Rebooting is also suggested if you
240 are unable to find another cygwin DLL.
244 To disable the usage of a unique key value of a certain Cygwin DLL, use
245 the <command>cygcheck --disable-unique-object-names Cygwin-DLL</command>
246 command. <literal>Cygwin-DLL</literal> is the Windows path (*not* a
247 Cygwin POSIX path) to the DLL for which you want to disable this feature.
248 Note that you have to stop all Cygwin processes running under this DLL,
249 before you're allowed to change this setting. For instance, run
250 <command>cygcheck</command> from a DOS command line for this purpose.</para>
252 <para>To re-enable the usage of a unique key, use the
253 <command>cygcheck --enable-unique-object-names Cygwin-DLL</command> command.
254 This option has the same characteristics as the
255 <literal>--disable-unique-object-names</literal> option</para>
257 <para>Finally, you can use
258 <command>cygcheck --show-unique-object-names Cygwin-DLL</command> to find out
259 if the given Cygwin DLL use unique object names or not. In contrast to the
260 <literal>--disable-...</literal> and <literal>--enable-...</literal> options,
261 the <literal>--show-unique-object-names</literal> option also works for
262 Cygwin DLLs which are currently in use.</para>
266 <sect2 id="cygpath"><title>cygpath</title>
269 Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME...
273 Convert Unix and Windows format paths, or output system path information
276 -d, --dos print DOS (short) form of NAMEs (C:\PROGRA~1\)
277 -m, --mixed like --windows, but with regular slashes (C:/WINNT)
278 -M, --mode report on mode of file (currently binmode or textmode)
279 -u, --unix (default) print Unix form of NAMEs (/cygdrive/c/winnt)
280 -w, --windows print Windows form of NAMEs (C:\WINNT)
281 -t, --type TYPE print TYPE form: 'dos', 'mixed', 'unix', or 'windows'
282 Path conversion options:
283 -a, --absolute output absolute path
284 -l, --long-name print Windows long form of NAMEs (with -w, -m only)
285 -p, --path NAME is a PATH list (i.e., '/bin:/usr/bin')
286 -s, --short-name print DOS (short) form of NAMEs (with -w, -m only)
287 -C, --codepage CP print DOS, Windows, or mixed pathname in Windows
288 codepage CP. CP can be a numeric codepage identifier,
289 or one of the reserved words ANSI, OEM, or UTF8.
290 If this option is missing, cygpath defaults to the
291 character set defined by the current locale.
293 -A, --allusers use `All Users' instead of current user for -D, -P
294 -D, --desktop output `Desktop' directory and exit
295 -H, --homeroot output `Profiles' directory (home root) and exit
296 -O, --mydocs output `My Documents' directory and exit
297 -P, --smprograms output Start Menu `Programs' directory and exit
298 -S, --sysdir output system directory and exit
299 -W, --windir output `Windows' directory and exit
300 -F, --folder ID output special folder with numeric ID and exit
302 -f, --file FILE read FILE for input; use - to read from STDIN
303 -o, --option read options from FILE as well (for use with --file)
304 -c, --close HANDLE close HANDLE (for use in captured process)
305 -i, --ignore ignore missing argument
306 -h, --help output usage information and exit
307 -v, --version output version information and exit
310 <para>The <command>cygpath</command> program is a utility that
311 converts Windows native filenames to Cygwin POSIX-style pathnames and
312 vice versa. It can be used when a Cygwin program needs to pass a file
313 name to a native Windows program, or expects to get a file name from a
314 native Windows program. Alternatively, <command>cygpath</command> can
315 output information about the location of important system directories
319 <para>The <literal>-u</literal> and <literal>-w</literal> options
320 indicate whether you want a conversion to UNIX (POSIX) format
321 (<literal>-u</literal>) or to Windows format (<literal>-w</literal>).
322 Use the <literal>-d</literal> to get DOS-style (8.3) file and path names.
323 The <literal>-m</literal> option will output Windows-style format
324 but with forward slashes instead of backslashes. This option is
325 especially useful in shell scripts, which use backslashes as an escape
328 <para> In combination with the <literal>-w</literal> option, you can use
329 the <literal>-l</literal> and <literal>-s</literal> options to use normal
330 (long) or DOS-style (short) form. The <literal>-d</literal> option is
331 identical to <literal>-w</literal> and <literal>-s</literal> together.
334 <para>The <literal>-C</literal> option allows to specify a Windows codepage
335 to print DOS and Windows paths created with one of the <literal>-d</literal>,
336 <literal>-m</literal>, or <literal>-w</literal> options. The default is to
337 use the character set of the current locale defined by one of the
338 internationalization environment variables <envar>LC_ALL</envar>,
339 <envar>LC_CTYPE</envar>, or <envar>LANG</envar>, see
340 <xref linkend="setup-locale"></xref>. This is sometimes not sufficent for
341 interaction with native Windows tools, which might expect native, non-ASCII
342 characters in a specific Windows codepage. Console tools, for instance, might
343 expect pathnames in the current OEM codepage, while graphical tools like
344 Windows Explorer might expect pathnames in the current ANSI codepage.</para>
346 <para>The <literal>-C</literal> option takes a single parameter:</para>
347 <itemizedlist spacing="compact">
348 <listitem><para><literal>ANSI</literal>, to specify the current ANSI codepage</para></listitem>
349 <listitem><para><literal>OEM</literal>, to specify the current OEM (console) codepage</para></listitem>
350 <listitem><para><literal>UTF8</literal>, to specify UTF-8.</para></listitem>
351 <listitem><para>A numerical, decimal codepage number, for instance 936 for GBK,
352 28593 for ISO-8859-3, etc. A full list of supported codepages is listed on the
354 <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
355 <literal>-C</literal> hasn't been specified at all.</para></listitem>
358 <para>The <literal>-p</literal> option means that you want to convert
359 a path-style string rather than a single filename. For example, the
360 PATH environment variable is semicolon-delimited in Windows, but
361 colon-delimited in UNIX. By giving <literal>-p</literal> you are
362 instructing <command>cygpath</command> to convert between these
365 <para>The <literal>-i</literal> option supresses the print out of the
366 usage message if no filename argument was given. It can be used in
367 make file rules converting variables that may be omitted
368 to a proper format. Note that <command>cygpath</command> output may
369 contain spaces (C:\Program Files) so should be enclosed in quotes.
373 <example id="utils-cygpath-ex"><title>Example <command>cygpath</command> usage</title>
381 XPATH="$(cygpath -C ANSI -w "${1}")";
388 <para>The capital options
389 <literal>-D</literal>, <literal>-H</literal>, <literal>-P</literal>,
390 <literal>-S</literal>, and <literal>-W</literal> output directories used
391 by Windows that are not the same on all systems, for example
392 <literal>-S</literal> might output C:\WINNT\system32 or C:\Windows\System32.
393 The <literal>-H</literal> shows the Windows profiles directory that can
394 be used as root of home. The <literal>-A</literal> option forces use of
395 the "All Users" directories instead of the current user for the
396 <literal>-D</literal>, <literal>-O</literal> and <literal>-P</literal>
398 The <literal>-F</literal> outputs other special folders specified by
399 their internal numeric code (decimal or 0xhex). For valid codes and
400 symbolic names, see the CSIDL_* definitions in the include file
401 /usr/include/w32api/shlobj.h from package w32api. The current valid
402 range of codes for folders is 0 (Desktop) to 59 (CDBurn area).
403 By default the output is in UNIX (POSIX) format;
404 use the <literal>-w</literal> or <literal>-d</literal> options to get
405 other formats.</para>
409 <sect2 id="dumper"><title>dumper</title>
412 Usage: dumper [OPTION] FILENAME WIN32PID
413 Dump core from WIN32PID to FILENAME.core
415 -d, --verbose be verbose while dumping
416 -h, --help output help information and exit
417 -q, --quiet be quiet while dumping (default)
418 -v, --version output version information and exit
421 <para>The <command>dumper</command> utility can be used to create a
422 core dump of running Windows process. This core dump can be later loaded
423 to <command>gdb</command> and analyzed. One common way to use
424 <command>dumper</command> is to plug it into cygwin's Just-In-Time
425 debugging facility by adding
428 error_start=x:\path\to\dumper.exe
431 to the <emphasis>CYGWIN</emphasis> environment variable. Please note that
432 <literal>x:\path\to\dumper.exe</literal> is Windows-style and not cygwin
433 path. If <literal>error_start</literal> is set this way, then dumper will
434 be started whenever some program encounters a fatal error.
438 <command>dumper</command> can be also be started from the command line to
439 create a core dump of any running process. Unfortunately, because of a Windows
440 API limitation, when a core dump is created and <command>dumper</command>
441 exits, the target process is terminated too.
445 To save space in the core dump, <command>dumper</command> doesn't write those
446 portions of target process' memory space that are loaded from executable and
447 dll files and are unchangeable, such as program code and debug info. Instead,
448 <command>dumper</command> saves paths to files which contain that data. When a
449 core dump is loaded into gdb, it uses these paths to load appropriate files.
450 That means that if you create a core dump on one machine and try to debug it on
451 another, you'll need to place identical copies of the executable and dlls in
452 the same directories as on the machine where the core dump was created.
457 <sect2 id="getfacl"><title>getfacl</title>
460 Usage: getfacl [-adn] FILE [FILE2...]
461 Display file and directory access control lists (ACLs).
463 -a, --all display the filename, the owner, the group, and
465 -d, --dir display the filename, the owner, the group, and
466 the default ACL of the directory, if it exists
467 -h, --help output usage information and exit
468 -n, --noname display user and group IDs instead of names
469 -v, --version output version information and exit
471 When multiple files are specified on the command line, a blank
472 line separates the ACLs for each file.
476 For each argument that is a regular file, special file or
477 directory, <command>getfacl</command> displays the owner, the group, and the
478 ACL. For directories <command>getfacl</command> displays additionally the
479 default ACL. With no options specified, <command>getfacl</command> displays
480 the filename, the owner, the group, and both the ACL and the default ACL, if
481 it exists. For more information on Cygwin and Windows ACLs, see
482 <xref linkend="ntsec"></xref> in the Cygwin User's Guide.
483 The format for ACL output is as follows:
489 user:name or uid:perm
491 group:name or gid:perm
495 default:user:name or uid:perm
497 default:group:name or gid:perm
504 <sect2 id="kill"><title>kill</title>
507 Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...]
509 Send signals to processes
511 -f, --force force, using win32 interface if necessary
512 -l, --list print a list of signal names
513 -s, --signal send signal (use kill --list for a list)
514 -h, --help output usage information and exit
515 -v, --version output version information and exit
518 <para>The <command>kill</command> program allows you to send arbitrary
519 signals to other Cygwin programs. The usual purpose is to end a
520 running program from some other window when ^C won't work, but you can
521 also send program-specified signals such as SIGUSR1 to trigger actions
522 within the program, like enabling debugging or re-opening log files.
523 Each program defines the signals they understand.</para>
525 <para>You may need to specify the full path to use <command>kill</command>
526 from within some shells, including <command>bash</command>, the default Cygwin
527 shell. This is because <command>bash</command> defines a
528 <command>kill</command> builtin function; see the <command>bash</command>
529 man page under <emphasis>BUILTIN COMMANDS</emphasis> for more information.
530 To make sure you are using the Cygwin version, try
533 $ /bin/kill --version
536 which should give the Cygwin <command>kill</command> version number and
537 copyright information.
540 <para>Unless you specific the <literal>-f</literal> option, the "pid" values
541 used by <command>kill</command> are the Cygwin pids, not the Windows pids.
542 To get a list of running programs and their Cygwin pids, use the Cygwin
543 <command>ps</command> program. <command>ps -W</command> will display
544 <emphasis>all</emphasis> windows pids.</para>
546 <para>The <command>kill -l</command> option prints the name of the
547 given signal, or a list of all signal names if no signal is given.</para>
549 <para>To send a specific signal, use the <literal>-signN</literal>
550 option, either with a signal number or a signal name (minus the "SIG"
551 part), as shown in these examples:</para>
553 <example id="utils-kill-ex"><title>Using the kill command</title>
555 <prompt>$</prompt> <userinput>kill 123</userinput>
556 <prompt>$</prompt> <userinput>kill -1 123</userinput>
557 <prompt>$</prompt> <userinput>kill -HUP 123</userinput>
558 <prompt>$</prompt> <userinput>kill -f 123</userinput>
562 <para>Here is a list of available signals, their numbers, and some
563 commentary on them, from the file
564 <literal><sys/signal.h></literal>, which should be considered
565 the official source of this information.</para>
571 SIGILL 4 illegal instruction (not reset when caught)
572 SIGTRAP 5 trace trap (not reset when caught)
573 SIGABRT 6 used by abort
574 SIGEMT 7 EMT instruction
575 SIGFPE 8 floating point exception
576 SIGKILL 9 kill (cannot be caught or ignored)
578 SIGSEGV 11 segmentation violation
579 SIGSYS 12 bad argument to system call
580 SIGPIPE 13 write on a pipe with no one to read it
581 SIGALRM 14 alarm clock
582 SIGTERM 15 software termination signal from kill
583 SIGURG 16 urgent condition on IO channel
584 SIGSTOP 17 sendable stop signal not from tty
585 SIGTSTP 18 stop signal from tty
586 SIGCONT 19 continue a stopped process
587 SIGCHLD 20 to parent on child stop or exit
588 SIGTTIN 21 to readers pgrp upon background tty read
589 SIGTTOU 22 like TTIN for output if (tp->t_local&LTOSTOP)
590 SIGPOLL 23 System V name for SIGIO
591 SIGXCPU 24 exceeded CPU time limit
592 SIGXFSZ 25 exceeded file size limit
593 SIGVTALRM 26 virtual time alarm
594 SIGPROF 27 profiling time alarm
595 SIGWINCH 28 window changed
596 SIGLOST 29 resource lost (eg, record-lock lost)
597 SIGUSR1 30 user defined signal 1
598 SIGUSR2 31 user defined signal 2
603 <sect2 id="locale"><title>locale</title>
606 Usage: locale [-amsuUvh]
607 or: locale [-ck] NAME
608 Get locale-specific information.
612 -a, --all-locales List all available supported locales
613 -c, --category-name List information about given category NAME
614 -k, --keyword-name Print information about given keyword NAME
615 -m, --charmaps List all available character maps
616 -s, --system Print system default locale
617 -u, --user Print user's default locale
618 -U, --utf Attach ".UTF-8" to the result
619 -v, --verbose More verbose output
623 <para><command>locale</command> without parameters prints information about
624 the current locale environment settings.</para>
626 <para>The <literal>-u</literal> option prints the current user's Windows
627 default locale to stdout. The <literal>-s</literal> option prints the
628 systems default locale instead. With the <literal>-U</literal> option
629 <command>locale</command> appends a ".UTF-8". This can be used in scripts
630 to set the Cygwin locale to the Windows user or system default, for instance:
634 bash$ export LANG=$(locale -uU)
639 <para>The <literal>-a</literal> option is helpful to learn which locales
640 are supported by your Windows machine. It prints all available locales
641 and the allowed modifiers. The <literal>-v</literal> option prints
642 additionally the English names of the language and territory connected
643 to this locale. Example:</para>
647 ar_SA Arabic (Saudi Arabia)
650 zh_TW Chinese (Traditional) (Taiwan)
651 zh_TW@cjknarrow Chinese (Traditional) (Taiwan)
653 de_AT German (Austria)
654 de_AT@euro German (Austria)
656 en_US English (United States)
657 en_GB English (United Kingdom)
658 en_AU English (Australia)
660 sr_RS Serbian (Cyrillic) (Serbia)
661 sr_RS@latin Serbian (Latin) (Serbia)
665 <para>The <literal>-m</literal> option prints the names of the available
666 charmaps supported by Cygwin to stdout.</para>
668 <para>Otherwise, if arguments are given, <command>locale</command> prints
669 the values assigned to these arguments. Arguments can be names of locale
670 categories (for instance: LC_CTYPE, LC_MONETARY), or names of keywords
671 supported in the locale categories (for instance: thousands_sep, charmap).
672 The <literal>-c</literal> option prints additionally the name of the category.
673 The <literal>-k</literal> option prints additionally the name of the keyword.
677 bash$ locale -ck LC_MESSAGES
683 messages-codeset="UTF-8"
690 <sect2 id="mkgroup"><title>mkgroup</title>
693 Usage: mkgroup [OPTION]...
694 Print /etc/group file to stdout
697 -l,--local [machine[,offset]]
698 print local groups with gid offset offset
699 (from local machine if no machine specified)
700 -L,--Local [machine[,offset]]
701 ditto, but generate groupname with machine prefix
702 -d,--domain [domain[,offset]]
703 print domain groups with gid offset offset
704 (from current domain if no domain specified)
705 -D,--Domain [domain[,offset]]
706 ditto, but generate groupname with machine prefix
707 -c,--current print current group
708 -C,--Current ditto, but generate groupname with machine or
710 -S,--separator char for -L, -D, -C use character char as domain\group
711 separator in groupname instead of the default '\'
712 -o,--id-offset offset change the default offset (10000) added to gids
713 in domain or foreign server accounts.
714 -g,--group groupname only return information for the specified group
715 one of -l, -L, -d, -D must be specified, too
716 -b,--no-builtin don't print BUILTIN groups
717 -U,--unix grouplist additionally print UNIX groups when using -l or -L
718 on a UNIX Samba server
719 grouplist is a comma-separated list of groupnames
720 or gid ranges (root,-25,50-100).
721 (enumerating large ranges can take a long time!)
722 -s,--no-sids (ignored)
724 -h,--help print this message
725 -v,--version print version information and exit
727 Default is to print local groups on stand-alone machines, plus domain
728 groups on domain controllers and domain member machines.
731 <para>The <command>mkgroup</command> program can be used to help
732 configure Cygwin by creating a <filename>/etc/group</filename>
733 file. Its use is essential to include Windows security information.</para>
735 <para>The command is initially called by <command>setup.exe</command> to
736 create a default <filename>/etc/group</filename>. This should be
737 sufficient in most circumstances. However, especially when working
738 in a multi-domain environment, you can use <command>mkgroup</command>
739 manually to create a more complete <filename>/etc/group</filename> file for
740 all domains. Especially when you have the same group name used on
741 multiple machines or in multiple domains, you can use the <literal>-D</literal>,
742 <literal>-L</literal> and <literal>-C</literal> options to create unique
743 domain\group style groupnames.</para>
745 <para>Note that this information is static. If you change the group
746 information in your system, you'll need to regenerate the group file
747 for it to have the new information.</para>
749 <para>The <literal>-d/-D</literal> and <literal>-l/-L</literal> options
750 allow you to specify where the information comes from, the
751 local SAM of a machine or from the domain, or both.
752 With the <literal>-d/-D</literal> options the program contacts a Domain
753 Controller, which my be unreachable or have restricted access.
754 Comma-separated from the machine or domain, you can specify an offset
755 which is used as base added to the group's RID to compute the gid
756 (offset + RID = gid). This allows you to create the same gids every time you
757 re-run <command>mkgroup</command>.
758 For very simple needs, an entry for the current user's group can be
759 created by using the option <literal>-c</literal> or <literal>-C</literal>.
760 If you want to use one of the <literal>-D</literal>, <literal>-L</literal>
761 or <literal>-C</literal> options, but you don't like the backslash as
762 domain/group separator, you can specify another separator using the
763 <literal>-S</literal> option, for instance:</para>
765 <example id="utils-mkgroup-ex"><title>Setting up group entry for current user with different domain/group separator</title>
767 <prompt>$</prompt> <userinput>mkgroup -C -S+ > /etc/group</userinput>
768 <prompt>$</prompt> <userinput>cat /etc/group</userinput>
769 DOMAIN+my_group:S-1-5-21-2913048732-1697188782-3448811101-1144:11144:
773 <para>The <literal>-o</literal> option allows for special cases
774 (such as multiple domains) where the GIDs might match otherwise.
775 The <literal>-g</literal> option only prints the information for one group.
776 The <literal>-U</literal> option allows you to enumerate the standard UNIX
777 groups on a Samba machine. It's used together with
778 <literal>-l samba-server</literal> or <literal>-L samba-server</literal>.
779 The normal UNIX groups are usually not enumerated, but they can show
780 up as a group in <command>ls -l</command> output.
785 <sect2 id="mkpasswd"><title>mkpasswd</title>
788 Usage: mkpasswd [OPTIONS]...
789 Print /etc/passwd file to stdout
792 -l,--local [machine[,offset]]
793 print local user accounts with uid offset offset
794 (from local machine if no machine specified)
795 -L,--Local [machine[,offset]]
796 ditto, but generate username with machine prefix
797 -d,--domain [domain[,offset]]
798 print domain accounts with uid offset offset
799 (from current domain if no domain specified)
800 -D,--Domain [domain[,offset]]
801 ditto, but generate username with domain prefix
802 -c,--current print current user
803 -C,--Current ditto, but generate username with machine or
805 -S,--separator char for -L, -D, -C use character char as domain\user
806 separator in username instead of the default '\'
807 -o,--id-offset offset change the default offset (10000) added to uids
808 in domain or foreign server accounts.
809 -u,--username username only return information for the specified user
810 one of -l, -L, -d, -D must be specified, too
811 -p,--path-to-home path use specified path instead of user account home dir
813 -m,--no-mount don't use mount points for home dir
814 -U,--unix userlist additionally print UNIX users when using -l or -L\
815 on a UNIX Samba server
816 userlist is a comma-separated list of usernames
817 or uid ranges (root,-25,50-100).
818 (enumerating large ranges can take a long time!)
819 -s,--no-sids (ignored)
820 -g,--local-groups (ignored)
821 -h,--help displays this message
822 -v,--version version information and exit
824 Default is to print local accounts on stand-alone machines, domain accounts
825 on domain controllers and domain member machines.
828 <para>The <command>mkpasswd</command> program can be used to help
829 configure Cygwin by creating a <filename>/etc/passwd</filename> from
830 your system information.
831 Its use is essential to include Windows security information. However,
832 the actual passwords are determined by Windows, not by the content of
833 <filename>/etc/passwd</filename>.</para>
835 <para>The command is initially called by <command>setup.exe</command> to
836 create a default <filename>/etc/passwd</filename>. This should be
837 sufficient in most circumstances. However, especially when working
838 in a multi-domain environment, you can use <command>mkpasswd</command>
839 manually to create a more complete <filename>/etc/passwd</filename> file for
840 all domains. Especially when you have the same user name used on
841 multiple machines or in multiple domains, you can use the <literal>-D</literal>,
842 <literal>-L</literal> and <literal>-C</literal> options to create unique
843 domain\user style usernames.</para>
845 <para>Note that this information is static. If you change the user
846 information in your system, you'll need to regenerate the passwd file
847 for it to have the new information.</para>
849 <para>The <literal>-d/-D</literal> and <literal>-l/-L</literal> options
850 allow you to specify where the information comes from, the
851 local machine or the domain (default or given), or both.
852 With the <literal>-d/-D</literal> options the program contacts the Domain
853 Controller, which may be unreachable or have restricted access.
854 Comma-separated from the machine or domain, you can specify an offset
855 which is used as base added to the user's RID to compute the uid
856 (offset + RID = uid). This allows to create the same uids every time you
857 re-run <command>mkpasswd</command>.
858 An entry for the current user can be created by using the
859 option <literal>-c</literal> or <literal>-C</literal>.
860 If you want to use one of the <literal>-D</literal>, <literal>-L</literal>
861 or <literal>-C</literal> options, but you don't like the backslash as
862 domain/group separator, you can specify another separator using the
863 <literal>-S</literal> option, similar to the <command>mkgroup</command>.
864 The <literal>-o</literal> option allows for special cases
865 (such as multiple domains) where the UIDs might match otherwise.
866 The <literal>-m</literal> option bypasses the current
867 mount table so that, for example, two users who have a Windows home
868 directory of H: could mount them differently. For more information on
869 SIDs, see <xref linkend="ntsec"></xref> in the Cygwin User's Guide. The
870 <literal>-p</literal> option causes <command>mkpasswd</command> to
871 use the specified prefix instead of the account home dir or <literal>/home/
872 </literal>. For example, this command:
874 <example id="utils-althome-ex"><title>Using an alternate home root</title>
876 <prompt>$</prompt> <userinput>mkpasswd -l -p "$(cygpath -H)" > /etc/passwd</userinput>
880 would put local users' home directories in the Windows 'Profiles' directory.
881 The <literal>-u</literal> option creates just an entry for
883 The <literal>-U</literal> option allows you to enumerate the standard UNIX
884 users on a Samba machine. It's used together with
885 <literal>-l samba-server</literal> or <literal>-L samba-server</literal>.
886 The normal UNIX users are usually not enumerated, but they can show
887 up as file owners in <command>ls -l</command> output.
892 <sect2 id="mount"><title>mount</title>
895 Usage: mount [OPTION] [<win32path> <posixpath>]
897 mount <posixpath>
898 Display information about mounted filesystems, or mount a filesystem
900 -a, --all mount all filesystems mentioned in fstab
901 -c, --change-cygdrive-prefix change the cygdrive path prefix to <posixpath>
902 -f, --force force mount, don't warn about missing mount
904 -h, --help output usage information and exit
905 -m, --mount-entries write fstab entries to replicate mount points
906 and cygdrive prefixes
907 -o, --options X[,X...] specify mount options
908 -p, --show-cygdrive-prefix show user and/or system cygdrive path prefix
909 -v, --version output version information and exit
912 <para>The <command>mount</command> program is used to map your drives
913 and shares onto Cygwin's simulated POSIX directory tree, much like as is
914 done by mount commands on typical UNIX systems. However, in contrast to
915 mount points given in <filename>/etc/fstab</filename>, mount points
916 created or changed with <command>mount</command> are not persistent. They
917 disappear immediately after the last process of the current user exited.
918 Please see <xref linkend="mount-table"></xref> for more information on the
919 concepts behind the Cygwin POSIX file system and strategies for using
920 mounts. To remove mounts temporarily, use <command>umount</command></para>
922 <sect3 id="utils-mount"><title>Using mount</title>
924 <para>If you just type <command>mount</command> with no parameters, it
925 will display the current mount table for you.</para>
927 <example id="utils-mount-ex">
928 <title>Displaying the current set of mount points</title>
930 <prompt>$</prompt> <userinput>mount</userinput>
931 c:\cygwin\bin on /usr/bin type ntfs (binary)
932 c:\cygwin\lib on /usr/lib type ntfs (binary)
933 c:\cygwin on / type ntfs (binary)
934 c: on /c type ntfs (binary,user,noumount)
935 d: on /d type fat (binary,user,noumount)
939 <para>In this example, c:\cygwin is the POSIX root and D drive is mapped to
940 <filename>/d</filename>. Note that in this case, the root mount is a
941 system-wide mount point that is visible to all users running Cygwin
942 programs, whereas the <filename>/d</filename> mount is only visible
943 to the current user.</para>
945 <para>The <command>mount</command> utility is also the mechanism for
946 adding new mounts to the mount table. The following example
947 demonstrates how to mount the directory
948 <filename>//pollux/home/joe/data</filename> to <filename>/data</filename>
949 for the duration of the current session.
952 <example id="utils-mount-add-ex">
953 <title>Adding mount points</title>
955 <prompt>$</prompt> <userinput>ls /data</userinput>
956 ls: /data: No such file or directory
957 <prompt>$</prompt> <userinput>mount //pollux/home/joe/data /data</userinput>
958 mount: warning - /data does not exist!
959 <prompt>$</prompt> <userinput>mount</userinput>
960 //pollux/home/joe/data on /data type smbfs (binary)
961 c:/cygwin/bin on /usr/bin type ntfs (binary)
962 c:/cygwin/lib on /usr/lib type ntfs (binary)
963 c:/cygwin on / type ntfs (binary)
964 c: on /c type ntfs (binary,user,noumount)
965 d: on /d type fat (binary,user,noumount)
969 <para>A given POSIX path may only exist once in the mount table. Attempts to
970 replace the mount will fail with a busy error. The <literal>-f</literal>
971 (force) option causes the old mount to be silently replaced with the new one,
972 provided the old mount point was a user mount point. It's not valid to
973 replace system-wide mount points. Additionally, the <literal>-f</literal>
974 option will silence warnings about the non-existence of directories at the
975 Win32 path location.</para>
978 The <literal>-o</literal> option is the method via which various options about
979 the mount point may be recorded. The following options are available (note that
980 most of the options are duplicates of other mount flags):</para>
983 acl - Use the filesystem's access control lists (ACLs) to
984 implement real POSIX permissions (default).
985 binary - Files default to binary mode (default).
986 cygexec - Treat all files below mount point as cygwin executables.
987 exec - Treat all files below mount point as executable.
988 noacl - Ignore ACLs and fake POSIX permissions.
989 nosuid - No suid files are allowed (currently unimplemented)
990 notexec - Treat all files below mount point as not executable.
991 override - Override immutable mount points.
992 posix=0 - Switch off case sensitivity for paths under this mount point.
993 posix=1 - Switch on case sensitivity for paths under this mount point
995 text - Files default to CRLF text mode line endings.
998 <para>For a more complete description of the mount options and the
999 <filename>/etc/fstab</filename> file, see
1000 <xref linkend="mount-table"></xref>.</para>
1002 <para>Note that all mount points added with <command>mount</command> are
1003 user mount points. System mount points can only be specified in
1004 the <filename>/etc/fstab</filename> file.</para>
1006 <para>If you added mount points to <filename>/etc/fstab</filename> or your
1007 <filename>/etc/fstab.d/<username></filename> file, you can add these
1008 mount points to your current user session using the <literal>-a/--all</literal>
1009 option, or by specifing the posix path alone on the command line. As an
1010 example, consider you added a mount point with the POSIX path
1011 <filename>/my/mount</filename>. You can add this mount point with either
1012 one of the following two commands to your current user session.</para>
1015 <prompt>$</prompt> <userinput>mount /my/mount</userinput>
1016 <prompt>$</prompt> <userinput>mount -a</userinput>
1019 <para>The first command just adds the <filename>/my/mount</filename> mount
1020 point to your current session, the <command>mount -a</command> adds all
1021 new mount points to your user session.</para>
1023 <para>If you change a mount point to point to another native path, or
1024 if you changed the flags of a mount point, you have to <command>umount</command>
1025 the mount point first, before you can add it again. Please note that
1026 all such added mount points are added as user mount points, and that the
1027 rule that system mount points can't be removed or replaced in a running
1028 session still applies.</para>
1031 The <literal>-m</literal> option causes the <command>mount</command> utility
1032 to output the current mount table in a series of fstab entries.
1033 You can save this output as a backup when experimenting with the mount table.
1034 Copy the output to <filename>/etc/fstab</filename> to restore the old state.
1035 It also makes moving your settings to a different machine much easier.</para>
1039 <sect3 id="utils-cygdrive"><title>Cygdrive mount points</title>
1041 <para>Whenever Cygwin cannot use any of the existing mounts to convert
1042 from a particular Win32 path to a POSIX one, Cygwin will, instead,
1043 convert to a POSIX path using a default mount point:
1044 <filename>/cygdrive</filename>. For example, if Cygwin accesses
1045 <filename>z:\foo</filename> and the z drive is not currently in the
1046 mount table, then <filename>z:\</filename> will be accessible as
1047 <filename>/cygdrive/z</filename>. The <command>mount</command> utility
1048 can be used to change this default automount prefix through the use of the
1049 "--change-cygdrive-prefix" option. In the following example, we will
1050 set the automount prefix to <filename>/mnt</filename>:</para>
1052 <example id="utils-cygdrive-ex">
1053 <title>Changing the default prefix</title>
1055 <prompt>$</prompt> <userinput>mount --change-cygdrive-prefix /mnt</userinput>
1059 <para>Note that the cygdrive prefix can be set both per-user and system-wide,
1060 and that as with all mounts, a user-specific mount takes precedence over the
1061 system-wide setting. The <command>mount</command> utility creates system-wide
1062 mounts by default if you do not specify a type.
1063 You can always see the user and system cygdrive prefixes with the
1064 <literal>-p</literal> option. Using the <literal>--options</literal>
1065 flag with <literal>--change-cygdrive-prefix</literal> makes all new
1066 automounted filesystems default to this set of options. For instance
1067 (using the short form of the command line flags)</para>
1069 <example id="utils-cygdrive-ex2">
1070 <title>Changing the default prefix with specific mount options</title>
1072 <prompt>$</prompt> <userinput>mount -c /mnt -o binary,noacl</userinput>
1079 <sect3 id="utils-limitations"><title>Limitations</title>
1081 <para>Limitations: there is a hard-coded limit of 30 mount
1082 points. Also, although you can mount to pathnames that do not start
1083 with "/", there is no way to make use of such mount points.</para>
1085 <para>Normally the POSIX mount point in Cygwin is an existing empty
1086 directory, as in standard UNIX. If this is the case, or if there is a
1087 place-holder for the mount point (such as a file, a symbolic link
1088 pointing anywhere, or a non-empty directory), you will get the expected
1089 behavior. Files present in a mount point directory before the mount
1090 become invisible to Cygwin programs.
1093 <para>It is sometimes desirable to mount to a non-existent directory,
1094 for example to avoid cluttering the root directory with names
1096 <filename>a</filename>, <filename>b</filename>, <filename>c</filename>
1098 Although <command>mount</command> will give you a warning, most
1099 everything will work properly when you refer to the mount point
1100 explicitly. Some strange effects can occur however.
1101 For example if your current working directory is
1102 <filename>/dir</filename>,
1103 say, and <filename>/dir/mtpt</filename> is a mount point, then
1104 <filename>mtpt</filename> will not show up in an <command>ls</command>
1106 <command>echo *</command> command and <command>find .</command> will
1108 find <filename>mtpt</filename>.
1115 <sect2 id="passwd"><title>passwd</title>
1118 Usage: passwd [OPTION] [USER]
1119 Change USER's password or password attributes.
1122 -l, --lock lock USER's account.
1123 -u, --unlock unlock USER's account.
1124 -c, --cannot-change USER can't change password.
1125 -C, --can-change USER can change password.
1126 -e, --never-expires USER's password never expires.
1127 -E, --expires USER's password expires according to system's
1128 password aging rule.
1129 -p, --pwd-not-required no password required for USER.
1130 -P, --pwd-required password is required for USER.
1131 -R, --reg-store-pwd enter password to store it in the registry for
1132 later usage by services to be able to switch
1133 to this user context with network credentials.
1136 -i, --inactive NUM set NUM of days before inactive accounts are disabled
1137 (inactive accounts are those with expired passwords).
1138 -n, --minage DAYS set system minimum password age to DAYS days.
1139 -x, --maxage DAYS set system maximum password age to DAYS days.
1140 -L, --length LEN set system minimum password length to LEN.
1143 -d, --logonserver SERVER connect to SERVER (e.g. domain controller).
1144 Default server is the local system, unless
1145 changing the current user, in which case the
1146 default is the content of $LOGONSERVER.
1147 -S, --status display password status for USER (locked, expired,
1148 etc.) plus global system password settings.
1149 -h, --help output usage information and exit.
1150 -v, --version output version information and exit.
1152 If no option is given, change USER's password. If no user name is given,
1153 operate on current user. System operations must not be mixed with user
1154 operations. Don't specify a USER when triggering a system operation.
1156 Don't specify a user or any other option together with the -R option.
1157 Non-Admin users can only store their password if cygserver is running.
1158 Note that storing even obfuscated passwords in the registry is not overly
1159 secure. Use this feature only if the machine is adequately locked down.
1160 Don't use this feature if you don't need network access within a remote
1161 session. You can delete your stored password by using `passwd -R' and
1162 specifying an empty password.
1165 <para> <command>passwd</command> changes passwords for user accounts.
1166 A normal user may only change the password for their own account,
1167 but administrators may change passwords on any account.
1168 <command>passwd</command> also changes account information, such as
1169 password expiry dates and intervals.</para>
1171 <para>For password changes, the user is first prompted for their old
1172 password, if one is present. This password is then encrypted and
1173 compared against the stored password. The user has only one chance to
1174 enter the correct password. The administrators are permitted to
1175 bypass this step so that forgotten passwords may be changed.</para>
1177 <para>The user is then prompted for a replacement password.
1178 <command>passwd</command> will prompt twice for this replacement and
1179 compare the second entry against the first. Both entries are required to
1180 match in order for the password to be changed.</para>
1182 <para>After the password has been entered, password aging information
1183 is checked to see if the user is permitted to change their password
1184 at this time. If not, <command>passwd</command> refuses to change the
1185 password and exits.</para>
1188 To get current password status information, use the
1189 <literal>-S</literal> option. Administrators can use
1190 <command>passwd</command> to perform several account maintenance
1191 functions (users may perform some of these functions on their own
1192 accounts). Accounts may be locked with the <literal>-l</literal> flag
1193 and unlocked with the <literal>-u</literal> flag. Similarly,
1194 <literal>-c</literal> disables a user's ability to change passwords, and
1195 <literal>-C</literal> allows a user to change passwords. For password
1196 expiry, the <literal>-e</literal> option disables expiration, while the
1197 <literal>-E</literal> option causes the password to expire according to
1198 the system's normal aging rules. Use <literal>-p</literal> to disable
1199 the password requirement for a user, or <literal>-P</literal> to require
1203 <para>Administrators can also use <command>passwd</command> to change
1204 system-wide password expiry and length requirements with the
1205 <literal>-i</literal>, <literal>-n</literal>, <literal>-x</literal>,
1206 and <literal>-L</literal> options. The <literal>-i</literal>
1207 option is used to disable an account after the password has been expired
1208 for a number of days. After a user account has had an expired password
1209 for <emphasis>NUM</emphasis> days, the user may no longer sign on to
1210 the account. The <literal>-n</literal> option is
1211 used to set the minimum number of days before a password may be changed.
1212 The user will not be permitted to change the password until
1213 <emphasis>MINDAYS</emphasis> days have elapsed. The
1214 <literal>-x</literal> option is used to set the maximum number of days
1215 a password remains valid. After <emphasis>MAXDAYS</emphasis> days, the
1216 password is required to be changed. Allowed values for the above options
1217 are 0 to 999. The <literal>-L</literal> option sets the minimum length of
1218 allowed passwords for users who don't belong to the administrators group
1219 to <emphasis>LEN</emphasis> characters. Allowed values for the minimum
1220 password length are 0 to 14. In any of the above cases, a value of 0
1221 means `no restrictions'.</para>
1224 All operations affecting the current user are by default run against
1225 the logon server of the current user (taken from the environment
1226 variable <envar>LOGONSERVER</envar>. When password or account information
1227 of other users should be changed, the default server is the local system.
1228 To change a user account on a remote machine, use the <literal>-d</literal>
1229 option to specify the machine to run the command against. Note that the
1230 current user must be a valid member of the administrators group on the remote
1231 machine to perform such actions.
1234 <para>Users can use the <command>passwd -R</command> to enter
1235 a password which then gets stored in a special area of the registry on the
1236 local system, which is also used by Windows to store passwords of accounts
1237 running Windows services. When a privileged Cygwin application calls the
1238 <command>set{e}uid(user_id)</command> system call, Cygwin checks if a
1239 password for that user has been stored in this registry area. If so, it
1240 uses this password to switch to this user account using that password.
1241 This allows you to logon through, for instance, <command>ssh</command> with
1242 public key authentication and get a full qualified user token with
1243 all credentials for network access. However, the method has some
1244 drawbacks security-wise. This is explained in more detail in
1245 <xref linkend="ntsec"></xref>.</para>
1247 <para>Please note that storing passwords in that registry area is a
1248 privileged operation which only administrative accounts are allowed to
1249 do. If normal, non-admin users should be allowed to enter their
1250 passwords using <command>passwd -R</command>, it's required to run
1251 <command>cygserver</command> as a service under the LocalSystem account
1252 before running <command>passwd -R</command>. This only affects storing
1253 passwords. Using passwords in privileged processes does not require
1254 <command>cygserver</command> to run.</para>
1256 <para>Limitations: Users may not be able to change their password on
1257 some systems.</para>
1261 <sect2 id="ps"><title>ps</title>
1264 Usage: ps [-aefls] [-u UID]
1265 Report process status
1267 -a, --all show processes of all users
1268 -e, --everyone show processes of all users
1269 -f, --full show process uids, ppids
1270 -h, --help output usage information and exit
1271 -l, --long show process uids, ppids, pgids, winpids
1272 -p, --process show information for specified PID
1273 -s, --summary show process summary
1274 -u, --user list processes owned by UID
1275 -v, --version output version information and exit
1276 -W, --windows show windows as well as cygwin processes
1277 With no options, ps outputs the long format by default
1280 <para>The <command>ps</command> program gives the status of all the
1281 Cygwin processes running on the system (ps = "process status"). Due
1282 to the limitations of simulating a POSIX environment under Windows,
1283 there is little information to give.
1287 The PID column is the process ID you need to give to the
1288 <command>kill</command> command. The PPID is the parent process ID,
1289 and PGID is the process group ID. The WINPID column is the process
1290 ID displayed by NT's Task Manager program. The TTY column gives which
1291 pseudo-terminal a process is running on, or a <literal>'?'</literal>
1292 for services. The UID column shows which user owns each process.
1293 STIME is the time the process was started, and COMMAND gives the name
1294 of the program running. Listings may also have a status flag in
1295 column zero; <literal>S</literal> means stopped or suspended (in other
1296 words, in the background), <literal>I</literal> means waiting for
1297 input or interactive (foreground), and <literal>O</literal> means
1302 By default, <command>ps</command> will only show processes owned by the
1303 current user. With either the <literal>-a</literal> or <literal>-e</literal>
1304 option, all user's processes (and system processes) are listed. There are
1305 historical UNIX reasons for the synonomous options, which are functionally
1306 identical. The <literal>-f</literal> option outputs a "full" listing with
1307 usernames for UIDs. The <literal>-l</literal> option is the default display
1308 mode, showing a "long" listing with all the above columns. The other display
1309 option is <literal>-s</literal>, which outputs a shorter listing of just
1310 PID, TTY, STIME, and COMMAND. The <literal>-u</literal> option allows you
1311 to show only processes owned by a specific user. The <literal>-p</literal>
1312 option allows you to show information for only the process with the
1313 specified PID. The <literal>-W</literal>
1314 option causes <command>ps</command> show non-Cygwin Windows processes as
1315 well as Cygwin processes. The WINPID is also the PID, and they can be killed
1316 with the Cygwin <command>kill</command> command's <literal>-f</literal>
1322 <sect2 id="regtool"><title>regtool</title>
1325 Usage: regtool [OPTION] (add|check|get|list|remove|unset|load|unload|save) KEY
1326 View or edit the Win32 registry
1329 add KEY\SUBKEY add new SUBKEY
1330 check KEY exit 0 if KEY exists, 1 if not
1331 get KEY\VALUE prints VALUE to stdout
1332 list KEY list SUBKEYs and VALUEs
1333 remove KEY remove KEY
1334 set KEY\VALUE [data ...] set VALUE
1335 unset KEY\VALUE removes VALUE from KEY
1336 load KEY\SUBKEY PATH load hive from PATH into new SUBKEY
1337 unload KEY\SUBKEY unload hive and remove SUBKEY
1338 save KEY\SUBKEY PATH save SUBKEY into new hive PATH
1340 Options for 'list' Action:
1341 -k, --keys print only KEYs
1342 -l, --list print only VALUEs
1343 -p, --postfix like ls -p, appends '\' postfix to KEY names
1345 Options for 'get' Action:
1346 -b, --binary print REG_BINARY data as hex bytes
1347 -n, --none print data as stream of bytes as stored in registry
1348 -x, --hex print numerical data as hex numbers
1350 Options for 'set' Action:
1351 -b, --binary set type to REG_BINARY (hex args or '-')
1352 -D, --dword-be set type to REG_DWORD_BIG_ENDIAN
1353 -e, --expand-string set type to REG_EXPAND_SZ
1354 -i, --integer set type to REG_DWORD
1355 -m, --multi-string set type to REG_MULTI_SZ
1356 -n, --none set type to REG_NONE
1357 -Q, --qword set type to REG_QWORD
1358 -s, --string set type to REG_SZ
1360 Options for 'set' and 'unset' Actions:
1361 -K<c>, --key-separator[=]<c> set key separator to <c> instead of '\'
1364 -h, --help output usage information and exit
1365 -q, --quiet no error output, just nonzero return if KEY/VALUE missing
1366 -v, --verbose verbose output, including VALUE contents when applicable
1367 -w, --wow64 access 64 bit registry view (ignored on 32 bit Windows)
1368 -W, --wow32 access 32 bit registry view (ignored on 32 bit Windows)
1369 -V, --version output version information and exit
1371 KEY is in the format [host]\prefix\KEY\KEY\VALUE, where host is optional
1372 remote host in either \\hostname or hostname: format and prefix is any of:
1373 root HKCR HKEY_CLASSES_ROOT (local only)
1374 config HKCC HKEY_CURRENT_CONFIG (local only)
1375 user HKCU HKEY_CURRENT_USER (local only)
1376 machine HKLM HKEY_LOCAL_MACHINE
1377 users HKU HKEY_USERS
1379 You can use forward slash ('/') as a separator instead of backslash, in
1380 that case backslash is treated as escape character
1381 Example: regtool.exe get '\user\software\Microsoft\Clock\iFormat'
1384 <para>The <command>regtool</command> program allows shell scripts
1385 to access and modify the Windows registry. Note that modifying the
1386 Windows registry is dangerous, and carelessness here can result
1387 in an unusable system. Be careful.</para>
1389 <para>The <literal>-v</literal> option means "verbose". For most
1390 commands, this causes additional or lengthier messages to be printed.
1391 Conversely, the <literal>-q</literal> option supresses error messages,
1392 so you can use the exit status of the program to detect if a key
1393 exists or not (for example).</para>
1395 <para>The <literal>-w</literal> option allows you to access the 64 bit view
1396 of the registry. Several subkeys exist in a 32 bit and a 64 bit version
1397 when running on Windows 64. Since Cygwin is running in 32 bit mode, it
1398 only has access to the 32 bit view of these registry keys. When using
1399 the <literal>-w</literal> switch, the 64 bit view is used and
1400 <command>regtool</command> can access the entire registry.
1401 This option is simply ignored when running on 32 bit Windows versions.
1404 <para>The <literal>-W</literal> option allows you to access the 32 bit view
1405 on the registry. The purpose of this option is mainly for symmetry. It
1406 permits creation of OS agnostic scripts which would also work in a hypothetical
1407 64 bit version of Cygwin.</para>
1409 <para>You must provide <command>regtool</command> with an
1410 <emphasis>action</emphasis> following options (if any). Currently,
1411 the action must be <literal>add</literal>, <literal>set</literal>,
1412 <literal>check</literal>, <literal>get</literal>, <literal>list</literal>,
1413 <literal>remove</literal>, <literal>set</literal>, or <literal>unset</literal>.
1416 <para>The <literal>add</literal> action adds a new key. The
1417 <literal>check</literal> action checks to see if a key exists (the
1418 exit code of the program is zero if it does, nonzero if it does not).
1419 The <literal>get</literal> action gets the value of a key,
1420 and prints it (and nothing else) to stdout. Note: if the value
1421 doesn't exist, an error message is printed and the program returns a
1422 non-zero exit code. If you give <literal>-q</literal>, it doesn't
1423 print the message but does return the non-zero exit code.</para>
1426 The <literal>list</literal> action lists the subkeys and values
1427 belonging to the given key. With <literal>list</literal>, the
1428 <literal>-k</literal> option instructs <command>regtool</command>
1429 to print only KEYs, and the <literal>-l</literal> option to print
1430 only VALUEs. The <literal>-p</literal> option postfixes a
1431 <literal>'/'</literal> to each KEY, but leave VALUEs with no
1432 postfix. The <literal>remove</literal> action
1433 removes a key. Note that you may need to remove everything in the key
1434 before you may remove it, but don't rely on this stopping you from
1435 accidentally removing too much.
1438 <para>The <literal>get</literal> action prints a value within a key.
1439 With the <literal>-b</literal> option, data is printed as hex bytes.
1440 <literal>-n</literal> allows to print the data as a typeless stream of
1441 bytes. Integer values (REG_DWORD, REG_QWORD) are usually printed
1442 as decimal values. The <literal>-x</literal> option allows to print
1443 the numbers as hexadecimal values.</para>
1445 <para>The <literal>set</literal> action sets a value within a key.
1446 <literal>-b</literal> means it's binary data (REG_BINARY).
1447 The binary values are specified as hex bytes in the argument list.
1448 If the argument is <literal>'-'</literal>, binary data is read
1450 <literal>-d</literal> or <literal>-i</literal> means the value is a 32 bit
1451 integer value (REG_DWORD).
1452 <literal>-D</literal> means the value is a 32 bit integer value in
1453 Big Endian representation (REG_DWORD_BIG_ENDIAN).
1454 <literal>-Q</literal> means the value is a 64 bit integer value (REG_QWORD).
1455 <literal>-s</literal> means the value is a string (REG_SZ).
1456 <literal>-e</literal> means it's an expanding string (REG_EXPAND_SZ)
1457 that contains embedded environment variables.
1458 <literal>-m</literal> means it's a multi-string (REG_MULTI_SZ).
1459 If you don't specify one of these, <command>regtool</command> tries to
1460 guess the type based on the value you give. If it looks like a
1461 number, it's a DWORD, unless it's value doesn't fit into 32 bit, in which
1462 case it's a QWORD. If it starts with a percent, it's an expanding
1463 string. If you give multiple values, it's a multi-string. Else, it's
1464 a regular string.</para>
1466 <para>The <literal>unset</literal> action removes a value from a key.</para>
1468 <para>The <literal>load</literal> action adds a new subkey and loads
1469 the contents of a registry hive into it.
1470 The parent key must be HKEY_LOCAL_MACHINE or HKEY_USERS.
1471 The <literal>unload</literal> action unloads the file and removes
1475 <para>The <literal>save</literal> action saves a subkey into a
1480 By default, the last "\" or "/" is assumed to be the separator between the
1481 key and the value. You can use the <literal>-K</literal> option to provide
1482 an alternate key/value separator character.
1487 <sect2 id="setfacl"><title>setfacl</title>
1490 Usage: setfacl [-r] (-f ACL_FILE | -s acl_entries) FILE...
1491 setfacl [-r] ([-d acl_entries] [-m acl_entries]) FILE...
1492 Modify file and directory access control lists (ACLs)
1494 -d, --delete delete one or more specified ACL entries
1495 -f, --file set ACL entries for FILE to ACL entries read
1497 -m, --modify modify one or more specified ACL entries
1498 -r, --replace replace mask entry with maximum permissions
1499 needed for the file group class
1500 -s, --substitute substitute specified ACL entries for the
1502 -h, --help output usage information and exit
1503 -v, --version output version information and exit
1505 At least one of (-d, -f, -m, -s) must be specified
1509 For each file given as parameter, <command>setfacl</command> will
1510 either replace its complete ACL (<literal>-s</literal>, <literal>-f</literal>),
1511 or it will add, modify, or delete ACL entries.
1512 For more information on Cygwin and Windows ACLs, see
1513 see <xref linkend="ntsec"></xref> in the Cygwin User's Guide.
1517 Acl_entries are one or more comma-separated ACL entries
1518 from the following list:
1527 Default entries are like the above with the additional
1528 default identifier. For example:
1530 d[efault]:u[ser]:uid:perm
1535 <emphasis>perm</emphasis> is either a 3-char permissions string in the form
1536 "rwx" with the character <literal>'-'</literal> for no permission
1537 or it is the octal representation of the permissions, a
1538 value from 0 (equivalent to "---") to 7 ("rwx").
1539 <emphasis>uid</emphasis> is a user name or a numerical uid.
1540 <emphasis>gid</emphasis> is a group name or a numerical gid.
1544 The following options are supported:
1548 <literal>-d</literal>
1549 Delete one or more specified entries from the file's ACL.
1550 The owner, group and others entries must not be deleted.
1551 Acl_entries to be deleted should be specified without
1552 permissions, as in the following list:
1556 d[efault]:u[ser]:uid
1557 d[efault]:g[roup]:gid
1564 <literal>-f</literal>
1565 Take the Acl_entries from ACL_FILE one per line. Whitespace
1566 characters are ignored, and the character "#" may be used
1567 to start a comment. The special filename "-" indicates
1568 reading from stdin. Note that you can use this with
1569 <command>getfacl</command> and <command>setfacl</command> to copy
1570 ACLs from one file to another:
1572 $ getfacl source_file | setfacl -f - target_file
1577 Required entries are:
1578 one user entry for the owner of the file,
1579 one group entry for the group of the file, and
1584 If additional user and group entries are given:
1585 a mask entry for the file group class of the file, and
1586 no duplicate user or group entries with the same uid/gid.
1590 If it is a directory:
1591 one default user entry for the owner of the file,
1592 one default group entry for the group of the file,
1593 one default mask entry for the file group class, and
1594 one default other entry.
1598 <literal>-m</literal>
1599 Add or modify one or more specified ACL entries. Acl_entries is a
1600 comma-separated list of entries from the same list as above.
1604 <literal>-r</literal>
1605 Causes the permissions specified in the mask
1606 entry to be ignored and replaced by the maximum permissions needed for
1607 the file group class.
1611 <literal>-s</literal>
1612 Like <literal>-f</literal>, but substitute the
1613 file's ACL with Acl_entries specified in a comma-separated list on the
1618 While the <literal>-d</literal> and <literal>-m</literal> options may be used
1619 in the same command, the <literal>-f</literal> and <literal>-s</literal>
1620 options may be used only exclusively.
1624 Directories may contain default ACL entries. Files created
1625 in a directory that contains default ACL entries will have
1626 permissions according to the combination of the current umask,
1627 the explicit permissions requested and the default ACL entries
1631 Limitations: Under Cygwin, the default ACL entries are not taken into
1637 <sect2 id="ssp"><title>ssp</title>
1640 Usage: ssp [options] low_pc high_pc command...
1641 Single-step profile COMMAND
1643 -c, --console-trace trace every EIP value to the console. *Lots* slower.
1644 -d, --disable disable single-stepping by default; use
1645 OutputDebugString ("ssp on") to enable stepping
1646 -e, --enable enable single-stepping by default; use
1647 OutputDebugString ("ssp off") to disable stepping
1648 -h, --help output usage information and exit
1649 -l, --dll enable dll profiling. A chart of relative DLL usage
1650 is produced after the run.
1651 -s, --sub-threads trace sub-threads too. Dangerous if you have
1653 -t, --trace-eip trace every EIP value to a file TRACE.SSP. This
1655 -v, --verbose output verbose messages about debug events.
1656 -V, --version output version information and exit
1658 Example: ssp 0x401000 0x403000 hello.exe
1662 SSP - The Single Step Profiler
1666 Original Author: DJ Delorie
1670 The SSP is a program that uses the Win32 debug API to run a program
1671 one ASM instruction at a time. It records the location of each
1672 instruction used, how many times that instruction is used, and all
1673 function calls. The results are saved in a format that is usable by
1674 the profiling program <command>gprof</command>, although
1675 <command>gprof</command> will claim the values
1676 are seconds, they really are instruction counts. More on that later.
1680 Because the SSP was originally designed to profile the cygwin DLL, it
1681 does not automatically select a block of code to report statistics on.
1682 You must specify the range of memory addresses to keep track of
1683 manually, but it's not hard to figure out what to specify. Use the
1684 "objdump" program to determine the bounds of the target's ".text"
1685 section. Let's say we're profiling cygwin1.dll. Make sure you've
1686 built it with debug symbols (else <command>gprof</command> won't run)
1687 and run objdump like this:
1690 $ objdump -h cygwin1.dll
1693 It will print a report like this:
1695 cygwin1.dll: file format pei-i386
1698 Idx Name Size VMA LMA File off Algn
1699 0 .text 0007ea00 61001000 61001000 00000400 2**2
1700 CONTENTS, ALLOC, LOAD, READONLY, CODE, DATA
1701 1 .data 00008000 61080000 61080000 0007ee00 2**2
1702 CONTENTS, ALLOC, LOAD, DATA
1708 The only information we're concerned with are the VMA of
1709 the .text section and the VMA of the section after it
1710 (sections are usually contiguous; you can also add the
1711 Size to the VMA to get the end address). In this case,
1712 the VMA is 0x61001000 and the ending address is either
1713 0x61080000 (start of .data method) or 0x0x6107fa00 (VMA+Size
1718 There are two basic ways to use SSP - either profiling a whole
1719 program, or selectively profiling parts of the program.
1723 To profile a whole program, just run <command>ssp</command> without options.
1724 By default, it will step the whole program. Here's a simple example, using
1728 $ ssp 0x61001000 0x61080000 hello.exe
1731 This will step the whole program. It will take at least 8 minutes on
1732 a PII/300 (yes, really). When it's done, it will create a file called
1733 "gmon.out". You can turn this data file into a readable report with
1734 <command>gprof</command>:
1737 $ gprof -b cygwin1.dll
1740 The "-b" means 'skip the help pages'. You can omit this until you're
1741 familiar with the report layout. The <command>gprof</command> documentation
1742 explains a lot about this report, but <command>ssp</command> changes a few
1743 things. For example, the first part of the report reports the amount of time
1744 spent in each function, like this:
1747 Each sample counts as 0.01 seconds.
1748 % cumulative self self total
1749 time seconds seconds calls ms/call ms/call name
1750 10.02 231.22 72.43 46 1574.57 1574.57 strcspn
1751 7.95 288.70 57.48 130 442.15 442.15 strncasematch
1754 The "seconds" columns are really CPU opcodes, 1/100 second per opcode.
1755 So, "231.22" above means 23,122 opcodes. The ms/call values are 10x
1756 too big; 1574.57 means 157.457 opcodes per call. Similar adjustments
1757 need to be made for the "self" and "children" columns in the second
1762 OK, so now we've got a huge report that took a long time to generate,
1763 and we've identified a spot we want to work on optimizing. Let's say
1764 it's the time() function. We can use SSP to selectively profile this
1765 function by using OutputDebugString() to control SSP from within the
1766 program. Here's a sample program:
1769 #include <windows.h>
1773 OutputDebugString("ssp on");
1775 OutputDebugString("ssp off");
1781 Then, add the <literal>-d</literal> option to ssp to default to
1782 *disabling* profiling. The program will run at full speed until the first
1783 OutputDebugString, then step until the second.
1784 You can then use <command>gprof</command> (as usual) to see the performance
1785 profile for just that portion of the program's execution.
1789 There are many options to ssp. Since step-profiling makes your
1790 program run about 1,000 times slower than normal, it's best to
1791 understand all the options so that you can narrow down the parts
1792 of your program you need to single-step.
1796 <literal>-v</literal> - verbose. This prints messages about threads
1797 starting and stopping, OutputDebugString calls, DLLs loading, etc.
1801 <literal>-t</literal> and <literal>-c</literal> - tracing.
1802 With <literal>-t</literal>, *every* step's address is written
1803 to the file "trace.ssp". This can be used to help debug functions,
1804 since it can trace multiple threads. Clever use of scripts can match
1805 addresses with disassembled opcodes if needed. Warning: creates
1806 *huge* files, very quickly. <literal>-c</literal> prints each address to
1807 the console, useful for debugging key chunks of assembler. Use
1808 <literal>addr2line -C -f -s -e foo.exe < trace.ssp > lines.ssp</literal>
1809 and then <literal>perl cvttrace</literal> to convert to symbolic traces.
1813 <literal>-s</literal> - subthreads. Usually, you only need to trace the
1814 main thread, but sometimes you need to trace all threads, so this enables that.
1815 It's also needed when you want to profile a function that only a
1816 subthread calls. However, using OutputDebugString automatically
1817 enables profiling on the thread that called it, not the main thread.
1821 <literal>-l</literal> - dll profiling. Generates a pretty table of how much
1822 time was spent in each dll the program used. No sense optimizing a function in
1823 your program if most of the time is spent in the DLL.
1824 I usually use the <literal>-v</literal>, <literal>-s</literal>, and
1825 <literal>-l</literal> options:
1828 $ ssp <literal>-v</literal> <literal>-s</literal> <literal>-l</literal> <literal>-d</literal> 0x61001000 0x61080000 hello.exe
1833 <sect2 id="strace"><title>strace</title>
1836 Usage: strace.exe [OPTIONS] <command-line>
1837 Usage: strace.exe [OPTIONS] -p <pid>
1838 Trace system calls and signals
1840 -b, --buffer-size=SIZE set size of output file buffer
1841 -d, --no-delta don't display the delta-t microsecond timestamp
1842 -f, --trace-children trace child processes (toggle - default true)
1843 -h, --help output usage information and exit
1844 -m, --mask=MASK set message filter mask
1845 -n, --crack-error-numbers output descriptive text instead of error
1846 numbers for Windows errors
1847 -o, --output=FILENAME set output file to FILENAME
1848 -p, --pid=n attach to executing program with cygwin pid n
1849 -q, --quiet toggle "quiet" flag. Defaults to on if "-p",
1851 -S, --flush-period=PERIOD flush buffered strace output every PERIOD secs
1852 -t, --timestamp use an absolute hh:mm:ss timestamp insted of
1853 the default microsecond timestamp. Implies -d
1854 -T, --toggle toggle tracing in a process already being
1855 -u, --usecs toggle printing of microseconds timestamp
1856 traced. Requires -p <pid>
1857 -v, --version output version information and exit
1858 -w, --new-window spawn program under test in a new window
1860 MASK can be any combination of the following mnemonics and/or hex values
1861 (0x is optional). Combine masks with '+' or ',' like so:
1863 --mask=wm+system,malloc+0x00800
1865 Mnemonic Hex Corresponding Def Description
1866 =========================================================================
1867 all 0x00001 (_STRACE_ALL) All strace messages.
1868 flush 0x00002 (_STRACE_FLUSH) Flush output buffer after each message.
1869 inherit 0x00004 (_STRACE_INHERIT) Children inherit mask from parent.
1870 uhoh 0x00008 (_STRACE_UHOH) Unusual or weird phenomenon.
1871 syscall 0x00010 (_STRACE_SYSCALL) System calls.
1872 startup 0x00020 (_STRACE_STARTUP) argc/envp printout at startup.
1873 debug 0x00040 (_STRACE_DEBUG) Info to help debugging.
1874 paranoid 0x00080 (_STRACE_PARANOID) Paranoid info.
1875 termios 0x00100 (_STRACE_TERMIOS) Info for debugging termios stuff.
1876 select 0x00200 (_STRACE_SELECT) Info on ugly select internals.
1877 wm 0x00400 (_STRACE_WM) Trace Windows msgs (enable _strace_wm).
1878 sigp 0x00800 (_STRACE_SIGP) Trace signal and process handling.
1879 minimal 0x01000 (_STRACE_MINIMAL) Very minimal strace output.
1880 exitdump 0x04000 (_STRACE_EXITDUMP) Dump strace cache on exit.
1881 system 0x08000 (_STRACE_SYSTEM) Serious error; goes to console and log.
1882 nomutex 0x10000 (_STRACE_NOMUTEX) Don't use mutex for synchronization.
1883 malloc 0x20000 (_STRACE_MALLOC) Trace malloc calls.
1884 thread 0x40000 (_STRACE_THREAD) Thread-locking calls.
1887 <para>The <command>strace</command> program executes a program, and
1888 optionally the children of the program, reporting any Cygwin DLL output
1889 from the program(s) to stdout, or to a file with the <literal>-o</literal>
1890 option. With the <literal>-w</literal> option, you can start an strace
1891 session in a new window, for example:
1894 $ strace -o tracing_output -w sh -c 'while true; do echo "tracing..."; done' &
1896 This is particularly useful for <command>strace</command> sessions that
1897 take a long time to complete.
1901 Note that <command>strace</command> is a standalone Windows program and so does
1902 not rely on the Cygwin DLL itself (you can verify this with
1903 <command>cygcheck</command>). As a result it does not understand symlinks.
1904 This program is mainly useful for debugging the Cygwin DLL itself.</para>
1908 <sect2 id="umount"><title>umount</title>
1911 Usage: umount.exe [OPTION] [<posixpath>]
1914 -h, --help output usage information and exit
1915 -U, --remove-user-mounts remove all user mounts
1916 -v, --version output version information and exit
1919 <para>The <command>umount</command> program removes mounts from the
1920 mount table in the current session. If you specify a POSIX path that
1921 corresponds to a current mount point, <command>umount</command> will
1922 remove it from the current mount table. Note that you can only remove
1923 user mount points. The <literal>-U</literal> flag may be used to
1924 specify removing all user mount points from the current user session.</para>
1926 <para>See <xref linkend="mount-table"></xref> for more information on the mount