utils.sgml patch for cygcheck, cygpath
Joshua Daniel Franklin
joshuadfranklin@yahoo.com
Sat Jul 6 17:53:00 GMT 2002
Here is a patch for utils.sgml that updates the documentation
for the first two utils (cygcheck and cygpath).
It includes Gary's "useful cygwinism" as an example for cygpath
replacing the old example of opening all your ".cc" files in
notepad. (Please tell me cygwin is not developed primarily in
notepad so this won't start a 3-way vi-emacs-notepad flame war.)
-------------- next part --------------
--- utils.sgml-orig 2002-07-04 17:02:47.000000000 -0500
+++ utils.sgml 2002-07-06 19:46:12.000000000 -0500
@@ -3,7 +3,10 @@
<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.</para>
+specifically for Cygwin. You may use the long or short option names
+interchangeably; for example, <literal>--help</literal> and
+<literal>-h</literal> function identically.
+</para>
<sect2 id="cygcheck"><title>cygcheck</title>
@@ -22,29 +25,20 @@ You must at least give either -s or -k o
<para>The <command>cygcheck</command> program is a diagnostic utility
that examines your system and reports the information that is
significant to the proper operation of Cygwin programs. It can give
-information about a specific program (or program) you are trying to
+information about specific programs or libraries you are trying to
run, general system information, or both. If you list one or more
programs on the command line, it will diagnose the runtime environment
-of that program or programs. If you specify the <literal>-s</literal>
+of that program or programs, providing the names of DLL files on which
+the program depends. If you specify the <literal>-s</literal>
option, it will give general system information. If you specify
<literal>-s</literal> and list one or more programs on the command line,
it reports on both.</para>
-<para>The <literal>-c</literal> option causes the "program" arguments
-to be interpreted as package names. <command>cygcheck</command> will
-report the current version of the package that you specify. With no
-arguments, <command>cygcheck</command> will report on all packages.</para>
-
-<para>The <command>cygcheck</command> program should be used to send
-information about your system to Cygnus for troubleshooting (if your
-support representative requests it). When asked to run this command,
-include all the options plus any commands you are having trouble with,
-and save the output so that you can mail it to Cygnus, like
-this:</para>
-
-<screen>
-<prompt>C:\Cygnus></prompt> <userinput>cygcheck -s -v -r -h > tocygnus.txt</userinput>
-</screen>
+<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
@@ -55,67 +49,75 @@ directories on the PATH. </para>
<para>The <literal>-r</literal> option causes
<command>cygcheck</command> to search your registry for information
-that is relevent to Cygnus programs. These registry entries are the
-ones that have "Cygnus" in the name. If you are paranoid about
+that is relevent to Cygwin programs. These registry entries are the
+ones that have "Cygwin" in the name. If you are paranoid about
privacy, you may remove information from this report, but please keep
-in mind that doing so makes it harder for Cygnus to diagnose your
-problems.</para>
+in mind that doing so makes it harder to diagnose your problems.</para>
-<para>The <literal>-h</literal> option prints additional helpful
-messages in the report, at the beginning of each section. It also
-adds table column headings. While this is useful information, it also
-adds some to the size of the report, so if you want a compact report
-or if you know what everything is already, just leave this out.</para>
+<para>The <literal>-c</literal> option causes the arguments
+to be interpreted as package names. <command>cygcheck</command> will
+report the current version of the package that you specify, or with no
+arguments, on all packages.</para>
+
+<para>The <command>cygcheck</command> program should be used to send
+information about your system for troubleshooting when requested.
+When asked to run this command save the output so that you can email it,
+for example:</para>
+
+<screen>
+<prompt>C:\cygwin></prompt> <userinput>cygcheck -s -v -r -h > cygcheck_output.txt</userinput>
+</screen>
</sect2>
<sect2 id="cygpath"><title>cygpath</title>
<screen>
-Usage: cygpath.exe (-u|-w|-t TYPE) [-c HANDLE] [-f FILE] [options] NAME
- cygpath.exe [-ADHPSW]
-Output type options (required):
- -u|--unix print Unix form of NAME (default)
- -w|--windows print Windows form of NAME
- -t|--type print Windows form of NAME with TYPE one of
- dos drive letter with backslashes (C:\WINNT)
- mixed drive letter with regular slashes (C:/WINNT)
+Usage: cygpath (-d|-m|-u|-w|-t TYPE) [-c HANDLE] [-f FILE] [options] NAME
+ cygpath [-ADHPSW]
+Output type options:
+ -d, --dos print DOS (short) form of NAME (C:\PROGRA~1\)
+ -m, --mixed like --windows, but with regular slashes (C:/WINNT)
+ -u, --unix (default) print Unix form of NAME (/cygdrive/c/winnt)
+ -w, --windows print Windows form of NAME (C:\WINNT)
+ -t, --type TYPE print TYPE form: 'dos', 'mixed', 'unix', or 'windows'
Path conversion options:
- -a|--absolute output absolute path
- -c|--close HANDLE close HANDLE (for use in captured process)
- -f|--file FILE read FILE for input; use - to read from STDIN
- -i|--ignore ignore missing argument
- -l|--long-name print Windows long form of NAME (with -w only)
- -p|--path NAME is a PATH list (i.e., '/bin:/usr/bin')
- -s|--short-name print Windows short form of NAME (with -w only)
-System information output:
- -A|--allusers use `All Users' instead of current user for -D, -P
- -D|--desktop output `Desktop' directory and exit
- -H|--homeroot output `Profiles' directory (home root) and exit
- -P|--smprograms output Start Menu `Programs' directory and exit
- -S|--sysdir output system directory and exit
- -W|--windir output `Windows' directory and exit
-Other options:
- -h|--help output usage information and exit
- -v|--version output version information and exit
+ -a, --absolute output absolute path
+ -l, --long-name print Windows long form of NAME (with -w, -m only)
+ -p, --path NAME is a PATH list (i.e., '/bin:/usr/bin')
+ -s, --short-name print DOS (short) form of NAME (with -w, -m only)
+System information:
+ -A, --allusers use `All Users' instead of current user for -D, -P
+ -D, --desktop output `Desktop' directory and exit
+ -H, --homeroot output `Profiles' directory (home root) and exit
+ -P, --smprograms output Start Menu `Programs' directory and exit
+ -S, --sysdir output system directory and exit
+ -W, --windir output `Windows' directory and exit
</screen>
<para>The <command>cygpath</command> program is a utility that
converts Windows native filenames to Cygwin POSIX-style pathnames and
-back. 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. You may use the long or short option names
-interchangeably, even though only the short ones are described
-here.</para>
+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 from Windows to UNIX (POSIX)
-format (<literal>-u</literal>) or a conversion from UNIX (POSIX) to
-Windows format (<literal>-w</literal>). You must give exactly
-one of these. To give neither or both is an error. Use the
-<literal>-l</literal> or <literal>-s</literal> option in combination
-with the <literal>-w</literal> option to convert to Windows long or
-short form.</para>
+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> In combination with the <literal>-w</literal> option, you can use
+the <literal>-l</literal> and <literal>-s</literal> options to use normal
+(long) or DOS-style (short) form. The <literal>-d</literal> option is
+identical to <literal>-w</literal> and <literal>-s</literal> together.
+</para>
<para>Caveat: The <literal>-l</literal> option does not work if the
<em>check_case</em> parameter of <em>CYGWIN</em> is set to <em>strict</em>,
@@ -131,16 +133,22 @@ 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 to a proper format that may be
-omitted.</para>
+make file rules converting variables that may be omitted
+to a proper format. Note that <command>cygpath</command> output may
+contain spaces (C:\Program Files) so should be enclosed in quotes.
+</para>
+
<example><title>Example cygpath usage</title>
<screen>
#!/bin/sh
-for i in `echo *.exe | sed 's/\.exe/.cc/'`
-do
- notepad "`cygpath -w $i`"
-done
+if [ "${1}" = "" ];
+ then
+ XPATH=".";
+ else
+ XPATH="$(cygpath -w "${1}")";
+ fi
+ explorer $XPATH &
</screen>
</example>
@@ -149,14 +157,15 @@ done
<literal>-S</literal>, and <literal>-W</literal> output directories used
by Windows that are not the same on all systems, for example
<literal>-S</literal> might output C:\WINNT\SYSTEM32 or C:\WINDOWS\SYSTEM.
-The <literal>-A</literal> option forces use of the "All Users" directories
-instead of the current user for the <literal>-D</literal> and
-<literal>-P</literal> options. The <literal>-H</literal> shows the Windows'
-profiles directory that can be used as root of home.
+The <literal>-H</literal> shows the Windows profiles directory that can
+be used as root of home. The <literal>-A</literal> option forces use of
+the "All Users" directories instead of the current user for the
+<literal>-D</literal> and <literal>-P</literal> options.
On Win9x systems with only a single user, <literal>-A</literal> has no
effect; <literal>-D</literal> and <literal>-AD</literal> would have the
-same output.
-The <literal>-ws</literal> options can be combined with the capital options.
+same output. By default the output is in UNIX (POSIX) format;
+use the <literal>-w</literal> or <literal>-d</literal> options to get
+other formats.
</sect2>
More information about the Cygwin-patches
mailing list