diff --git a/winsup/utils/utils.sgml b/winsup/utils/utils.sgml index 2cbec03bb..badd89be2 100644 --- a/winsup/utils/utils.sgml +++ b/winsup/utils/utils.sgml @@ -268,12 +268,12 @@ The format for ACL output is as follows: Usage: kill [-f] [-signal] [-s signal] pid1 [pid2 ...] -kill -l [signal] --f, --force force, using win32 interface if necessary --l, --list print a list of signal names --s, --signal send signal (use kill --list for a list) --h, --help output usage information and exit --v, --version output version information and exit + kill -l [signal] + -f, --force force, using win32 interface if necessary + -l, --list print a list of signal names + -s, --signal send signal (use kill --list for a list) + -h, --help output usage information and exit + -v, --version output version information and exit The kill program allows you to send arbitrary @@ -388,9 +388,11 @@ One of `-l' or `-d' must be given on NT/W2K. The mkgroup program can be used to help configure your Windows system to be more UNIX-like by creating an initial /etc/group substitute (some commands need this -file) from your system information. It only works on NT. -To initially set up your machine, -you'd do something like this: +file) from your system information. It only works on the NT series +(Windows NT, 2000, and XP). mkgroup does not work on +the Win9x series (Windows 95, 98, and Me) because they lack the security model +to support it. To initially set up your machine, you'd do something like +this: Setting up the groups file @@ -405,7 +407,16 @@ for it to have the new information. The -d and -l options allow you to specify where the information comes from, either the -local machine or the default (or given) domain. +local machine or the default (or given) domain. The -o +option allows for special cases (such as multiple domains) where the GIDs +might match otherwise. The -s +option omits the NT Security Identifier (SID). For more information on +SIDs, see in the Cygwin User's Guide. The +-u option causes mkgroup to +enumerate the users for each group, placing the group members in the +gr_mem (last) field. Note that this can greatly increase +the time for mkgroup to run in a large domain. + @@ -438,8 +449,11 @@ One of `-l', `-d' or `-g' must be given on NT/W2K. The mkpasswd program can be used to help configure your Windows system to be more UNIX-like by creating an initial /etc/passwd substitute (some commands -need this file) from your system information. It only works on NT. -To initially set up your machine, you'd do something like this: +need this file) from your system information. It only works on the NT series +(Windows NT, 2000, and XP). mkpasswd does not work on +the Win9x series (Windows 95, 98, and Me) because they lack the security model +to support it. To initially set up your machine, you'd do something like +this: Setting up the passwd file @@ -454,7 +468,221 @@ for it to have the new information. The -d and -l options allow you to specify where the information comes from, either the -local machine or the default (or given) domain. +local machine or the default (or given) domain. The -o +option allows for special cases (such as multiple domains) where the UIDs +might match otherwise. The -g option creates a local +user that corresponds to each local group. This is because NT assigns groups +file ownership. The -m option bypasses the current +mount table so that, for example, two users who have a Windows home +directory of H: could mount them differently. The -s +option omits the NT Security Identifier (SID). For more information on +SIDs, see in the Cygwin User's Guide. The +-p option causes mkpasswd to +use a prefix other than /home/. For example, this command: + +Using an alternate home root + +$ mkpasswd -l -p "$(cygpath -H)" > /etc/passwd + + + +would put local users' home directories in the Windows 'Profiles' directory. +The -u option allows mkpasswd to +search for a specific username, greatly reducing the amount of time it +takes in a large domain. + + + +mount + + +Usage: mount [OPTION] [ ] + -b, --binary text files are equivalent to binary files + (newline = \n) + -c, --change-cygdrive-prefix change the cygdrive path prefix to + -f, --force force mount, don't warn about missing mount + point directories + -h, --help output usage information and exit + -m, --mount-commands write mount commands to replace user and + system mount points and cygdrive prefixes + -p, --show-cygdrive-prefix show user and/or system cygdrive path prefix + -s, --system (default) add system-wide mount point + -t, --text (default) text files get \r\n line endings + -u, --user add user-only mount point + -v, --version output version information and exit + -x, --executable treat all files under mount point as executables + -E, --no-executable treat all files under mount point as + non-executables + -X, --cygwin-executable treat all files under mount point as cygwin + executables + + +The mount program is used to map your drives +and shares onto Cygwin's simulated POSIX directory tree, much like as is +done by mount commands on typical UNIX systems. Please see + for more information on the concepts +behind the Cygwin POSIX file system and strategies for using +mounts. + +Using mount + +If you just type mount with no parameters, it +will display the current mount table for you. + + +Displaying the current set of mount points + +c:\cygwin\> mount +c:\cygwin\bin on /usr/bin type system (binmode) +c:\cygwin\lib on /usr/lib type system (binmode) +c:\cygwin on / type system (binmode) +c: on /c type user (binmode,noumount) +d: on /d type user (binmode,noumount) + + + +In this example, c:\cygwin is the POSIX root and D drive is mapped to +/d. Note that in this case, the root mount is a +system-wide mount point that is visible to all users running Cygwin +programs, whereas the /d mount is only visible +to the current user. + +The mount utility is also the mechanism for +adding new mounts to the mount table. The following example +demonstrates how to mount the directory +\\pollux\home\joe\data to /data. + + + +Adding mount points + +c:\cygwin\> ls /data +ls: /data: No such file or directory +c:\cygwin\> mount \\pollux\home\joe\data /data +mount: warning - /data does not exist! +c:\cygwin\> mount +\\pollux\home\joe\data on /data type sytem (binmode) +c:\cygwin\bin on /usr/bin type system (binmode) +c:\cygwin\lib on /usr/lib type system (binmode) +c:\cygwin on / type system (binmode) +c: on /c type user (binmode,noumount) +d: on /d type user (binmode,noumount) + + + +Note that mount was invoked from the Windows +command shell in the previous example. In many Unix shells, including +bash, it is legal and convenient to use the forward "/" in Win32 +pathnames since the "\" is the shell's escape character. + +The -s flag to mount is used to add a mount +in the system-wide mount table used by all Cygwin users on the system, +instead of the user-specific one. System-wide mounts are displayed +by mount as being of the "system" type, as is the +case for the / partition in the last example. +Under Windows NT, only those users with Administrator priviledges are +permitted to modify the system-wide mount table. + +Note that a given POSIX path may only exist once in the user +table and once in the global, system-wide table. Attempts to replace +the mount will fail with a busy error. The -f (force) flag causes +the old mount to be silently replaced with the new one. It will also +silence warnings about the non-existence of directories at the Win32 +path location. + +The -b flag is used to instruct Cygwin to treat binary and +text files in the same manner by default. Binary mode mounts are +marked as "binmode" in the Flags column of mount +output. By default, mounts are in text mode ("textmode" in the Flags +column). + +Normally, files ending in certain extensions (.exe, .com, .bat, .cmd) +are assumed to be executable. Files whose first two characters begin with +'#!' are also considered to be executable. +The -x flag is used to instruct Cygwin that the +mounted file is "executable". If the -x flag is used +with a directory then all files in the directory are executable. +This option allows other files to be marked as executable and avoids the +overhead of opening each file to check for a '#!'. The -X +option is very similar to -x, but also prevents Cygwin +from setting up commands and environment variables for a normal Windows +program, adding another small performance gain. The opposite of these +flags is the -E flag, which means that no files should be +marked as executable. + + +The -m option causes the mount utility +to output a series of commands that could recreate both user and system mount +points. You can save this output as a backup when experimenting with the +mount table. It also makes moving your settings to a different machine +much easier. + + + + +Cygdrive mount points + +Whenever Cygwin cannot use any of the existing mounts to convert +from a particular Win32 path to a POSIX one, Cygwin will, instead, +convert to a POSIX path using a default mount point: +/cygdrive. For example, if Cygwin accesses +z:\foo and the z drive is not currently in the +mount table, then z:\ will be accessible as +/cygdrive/z. The mount utility +can be used to change this default automount prefix through the use of the +"--change-cygdrive-prefix" option. In the following example, we will +set the automount prefix to /: + + +Changing the default prefix + +c:\cygwin\> mount --change-cygdrive-prefix / + + + +Note that you if you set a new prefix in this manner, you can +specify the -s flag to make this the system-wide default +prefix. By default, the cygdrive-prefix applies only to the current user. +You can always see the user and system cygdrive prefixes with the +-p option. Using the -b +flag with --change-cygdrive-prefix makes all new +automounted filesystems default to binary mode file accesses. + + + +Limitations + +Limitations: there is a hard-coded limit of 30 mount +points. Also, although you can mount to pathnames that do not start +with "/", there is no way to make use of such mount points. + +Normally the POSIX mount point in Cygwin is an existing empty +directory, as in standard UNIX. If this is the case, or if there is a +place-holder for the mount point (such as a file, a symbolic link +pointing anywhere, or a non-empty directory), you will get the expected +behavior. Files present in a mount point directory before the mount +become invisible to Cygwin programs. + + +It is sometimes desirable to mount to a non-existent directory, +for example to avoid cluttering the root directory with names +such as +a, b, c +pointing to disks. +Although mount will give you a warning, most +everything will work properly when you refer to the mount point +explicitly. Some strange effects can occur however. +For example if your current working directory is +/dir, +say, and /dir/mtpt is a mount point, then +mtpt will not show up in an ls +or +echo * command and find . will +not +find mtpt. + + + @@ -535,195 +763,6 @@ some systems. -mount - - -Usage: mount [OPTION] [ ] - -b, --binary text files are equivalent to binary files - (newline = \n) - -c, --change-cygdrive-prefix change the cygdrive path prefix to - -f, --force force mount, don't warn about missing mount - point directories - -h, --help output usage information and exit - -m, --mount-commands write mount commands to replace user and - system mount points and cygdrive prefixes - -p, --show-cygdrive-prefix show user and/or system cygdrive path prefix - -s, --system (default) add system-wide mount point - -t, --text (default) text files get \r\n line endings - -u, --user add user-only mount point - -v, --version output version information and exit - -x, --executable treat all files under mount point as executables - -E, --no-executable treat all files under mount point as - non-executables - -X, --cygwin-executable treat all files under mount point as cygwin - executables - - -The mount program is used to map your drives -and shares onto Cygwin's simulated POSIX directory tree, much like as is -done by mount commands on typical UNIX systems. Please see - for more information on the concepts -behind the Cygwin POSIX file system and strategies for using -mounts. - -Using mount - -If you just type mount with no parameters, it -will display the current mount table for you. - - -Displaying the current set of mount points - -c:\cygnus\> mount -Device Directory Type Flags -D: /d user textmode -C: / system textmode - - - -In this example, the C -drive is the POSIX root and D drive is mapped to -/d. Note that in this case, the root mount is a -system-wide mount point that is visible to all users running Cygwin -programs, whereas the /d mount is only visible -to the current user. - -The mount utility is also the mechanism for -adding new mounts to the mount table. The following example -demonstrates how to mount the directory -C:\cygnus\cygwin-b20\H-i586-cygwin32\bin -to /bin and the network directory -\\pollux\home\joe\data to /data. -/bin is assumed to already exist. - - -Adding mount points - -c:\cygnus\> ls /bin /data -ls: /data: No such file or directory -c:\cygnus\> mount C:\cygnus\cygwin-b20\H-i586-cygwin32\bin /bin -c:\cygnus\> mount \\pollux\home\joe\data /data -Warning: /data does not exist! -c:\cygnus\> mount -Device Directory Type Flags -\\pollux\home\joe\data /data user textmode -C:\cygnus\cygwin-b20\H-i586-cygwin32\bin /bin user textmode -D: /d user textmode -\\.\tape1: /dev/st1 user textmode -\\.\tape0: /dev/st0 user textmode -\\.\b: /dev/fd1 user textmode -\\.\a: /dev/fd0 user textmode -C: / system textmode -c:\cygnus\> ls /bin/sh -/bin/sh - - - -Note that mount was invoked from the Windows -command shell in the previous example. In many Unix shells, including -bash, it is legal and convenient to use the forward "/" in Win32 -pathnames since the "\" is the shell's escape character. - -The "-s" flag to mount is used to add a mount -in the system-wide mount table used by all Cygwin users on the system, -instead of the user-specific one. System-wide mounts are displayed -by mount as being of the "system" type, as is the -case for the / partition in the last example. -Under Windows NT, only those users with Administrator priviledges are -permitted to modify the system-wide mount table. - -Note that a given POSIX path may only exist once in the user -table and once in the global, system-wide table. Attempts to replace -the mount will fail with a busy error. The "-f" (force) flag causes -the old mount to be silently replaced with the new one. It will also -silence warnings about the non-existence of directories at the Win32 -path location. - -The "-b" flag is used to instruct Cygwin to treat binary and -text files in the same manner by default. Binary mode mounts are -marked as "binmode" in the Flags column of mount -output. By default, mounts are in text mode ("textmode" in the Flags -column). - -The "-x" flag is used to instruct Cygwin that the mounted file -is "executable". If the "-x" flag is used with a directory then -all files in the directory are executable. Files ending in certain -extensions (.exe, .com, .bat, .cmd) are assumed to be executable -by default. Files whose first two characters begin with '#!' are -also considered to be executable. This option allows other files -to be marked as executable and avoids the overhead of opening each -file to check for a '#!'. - - - -Cygdrive mount points - -Whenever Cygwin cannot use any of the existing mounts to convert -from a particular Win32 path to a POSIX one, Cygwin will, instead, -convert to a POSIX path using a default mount point: -/cygdrive. For example, if Cygwin accesses -Z:\foo and the Z drive is not currently in the -mount table, then Z:\ will be accessible as -/cygdrive/Z. The default prefix of -/cygdrive may be changed via the - command. - -The mount utility can be used to change this -default automount prefix through the use of the -"--change-cygdrive-prefix" flag. In the following example, we will -set the automount prefix to /: - - -Changing the default prefix - -c:\cygnus\> mount --change-cygdrive-prefix / - - - -Note that you if you set a new prefix in this manner, you can -specify the "-s" flag to make this the system-wide default prefix. By -default, the cygdrive-prefix applies only to the current user. In the -same way, you can specify the "-b" flag such that all new automounted -filesystems default to binary mode file accesses. - - - -Limitations - -Limitations: there is a hard-coded limit of 30 mount -points. Also, although you can mount to pathnames that do not start -with "/", there is no way to make use of such mount points. - -Normally the POSIX mount point in Cygwin is an existing empty -directory, as in standard UNIX. If this is the case, or if there is a -place-holder for the mount point (such as a file, a symbolic link -pointing anywhere, or a non-empty directory), you will get the expected -behavior. Files present in a mount point directory before the mount -become invisible to Cygwin programs. - - -It is sometimes desirable to mount to a non-existent directory, -for example to avoid cluttering the root directory with names -such as -a, b, c -pointing to disks. -Although mount will give you a warning, most -everything will work properly when you refer to the mount point -explicitly. Some strange effects can occur however. -For example if your current working directory is -/dir, -say, and /dir/mtpt is a mount point, then -mtpt will not show up in an ls -or -echo * command and find . will -not -find mtpt. - - - - - - ps