Background[]
It's a system (shell) command. It's a commandline interface to the cygwin API.
(from the Cygwin User Guide ([UG]):
| The cygpath program is a utility that converts Windows native filenames to Cygwin POSIX-style pathnames and vice versa. It can be used when a Cygwin program needs to pass a file name to a native Windows program, or expects to get a file name from a native Windows program. Alternatively, cygpath can output information about the location of important system directories in either format. |
Synopsis[]
cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME... cygpath [-c HANDLE] cygpath [-ADHOPSW] cygpath [-F ID] |
Note something important about the syntax of the first invocation format. The NAME (non-option parameter) has an ellipsis after it. In many man pages where the intended meaning is "more of the same kind of parameter may follow," the format of that line would be slightly different:
cygpath (-d|-m|-u|-w|-t TYPE) [-f FILE] [OPTION]... NAME [...NAME] |
as an example. This subtlety evaded my notice even after many years of using cygpath on the commandline and in programs.
The important thing to notice is that cygpath accepts multiple pathname specs as arguments. Therefore cygpath must have a way of making output that consists of a list of path specs converted to the requested format. The making of a list as text output naturally requires some sort of delimiter. The delimiter used by cygpath is the native newline control code \r.
When using just a single pathname spec (NAME) argument cygpath will still append a native newline control sequence \r to the output. In many cases the user will never notice this. For example, if a sh shell script uses the output of cygpath to assign to a shell variable:
$ declare CYGUSERHOME=$(cygpath -ma ~)
then CYGUSERHOME will contain a string without a newline
CYGUSERHOME=C:/Users/somian/AppData/Cygwin
However, if the program that invokes cygpath is not aware of cygwin's nature as a adaptation of *nix semantics to MS Windows - including line ending character, filesystem semantics, special device files, etc. - all that *nix stuff that we love - then that program may not automatically "strip" the trailing control code from the output of cygpath:
$ C:/Strawberry/Perl/bin/perl.exe -e 'print qx(cygpath -ma $ENV{HOME}) .q[STOP_HERE]'
which gives the output
C:/Users/somian/AppData/Cygwin STOP_HERE
Likewise, the NMSW (Native Microsoft Windows) Vim text editor does not strip trailing control codes from the output of cygpath.
Summary[]
For these and any other non-cygwin applications to utilize cygpath, we must be careful to process the output of cygpath for removal of the trailing \r which will be present even if we have passed only a single NAME pathname spec to cygpath.
--Perlsomian (talk) 18:16, March 26, 2013 (UTC)