utils.sgml

cygwin, 著名的在win32下模拟unix操作系统的东东

</sect3>

</sect2>

<sect2 id="passwd"><title>passwd</title>

<screen>
Usage: passwd (-l|-u|-S) [USER]
       passwd [-i NUM] [-n MINDAYS] [-x MAXDAYS] [-L LEN]

User operations:
 -l, --lock      lock USER's account
 -u, --unlock    unlock USER's account
 -S, --status    display password status for USER (locked, expired, etc.)

System operations:
 -i, --inactive  set NUM of days before inactive accounts are disabled
                 (inactive accounts are those with expired passwords)
 -n, --minage    set system minimum password age to MINDAYS
 -x, --maxage    set system maximum password age to MAXDAYS
 -L, --length    set system minimum password length to LEN

Other options:
 -h, --help      output usage information and exit
 -v, --version   output version information and exit
</screen>

<para> <command>passwd</command> changes passwords for user accounts.
A normal user may only change the password for their own account,
but administrators may change passwords on any account.
<command>passwd</command> also changes account information, such as
password expiry dates and intervals.</para>

<para>Password changes: The user is first prompted for their old
password, if one is present.  This password is then encrypted and
compared against the stored password.  The user has only one chance to
enter the correct password.  The administrators are permitted to
bypass this step so that forgotten passwords may be changed.</para>

<para>The user is then prompted for a replacement password.
<command>passwd</command> will prompt twice for this replacement and 
compare the second entry against the first.  Both entries are require to 
match in order for the password to be changed.</para>

<para>After the password has been entered, password aging information
is checked to see if the user is permitted to change their password
at this time.  If not, <command>passwd</command> refuses to change the
password and exits.</para>

<para>Account maintenance: User accounts may be locked and unlocked with the
<literal>-l</literal> and <literal>-u</literal> flags.  The
<literal>-l</literal> option disables an account.  The <literal>-u</literal>
option re-enables an account.</para>

<para>The account status may be given with the <literal>-S</literal>
option.  The status information is self explanatory.</para>

<para>Administrators can also use <command>passwd</command> to change
system-wide password expiry and length requirements with the
<literal>-i</literal>, <literal>-n</literal>, <literal>-x</literal>,
and <literal>-L</literal> options.  The <literal>-i</literal>
option is used to disable an account after the password has been expired
for a number of days.  After a user account has had an expired password
for <emphasis>NUM</emphasis> days, the user may no longer sign on to
the account.  The <literal>-n</literal> option is
used to set the minimum number of days before a password may be changed.
The user will not be permitted to change the password until
<emphasis>MINDAYS</emphasis> days have elapsed.  The
<literal>-x</literal> option is used to set the maximum number of days
a password remains valid.  After <emphasis>MAXDAYS</emphasis> days, the
password is required to be changed.  Allowed values for the above options 
are 0 to 999.  The <literal>-L</literal> option sets the minimum length of 
allowed passwords for users who don't belong to the administrators group
to <emphasis>LEN</emphasis> characters.  Allowed values for the minimum
password length are 0 to 14.  In any of the above cases, a value of 0
means `no restrictions'.</para>

<para>Limitations: Users may not be able to change their password on
some systems.</para>

</sect2>

<sect2 id="ps"><title>ps</title>

<screen>
Usage: ps [-aefls] [-u UID]
 -a, --all       show processes of all users
 -e, --everyone  show processes of all users
 -f, --full      show process uids, ppids
 -h, --help      output usage information and exit
 -l, --long      show process uids, ppids, pgids, winpids
 -s, --summary   show process summary
 -u, --user      list processes owned by UID
 -v, --version   output version information and exit
 -W, --windows   show windows as well as cygwin processes
With no options, ps outputs the long format by default
</screen>

<para>The <command>ps</command> program gives the status of all the
Cygwin processes running on the system (ps = "process status").  Due
to the limitations of simulating a POSIX environment under Windows,
there is little information to give.  
</para>

<para>
The PID column is the process ID you need to give to the 
<command>kill</command> command. The PPID is the parent process ID,
and PGID is the process group ID.  The WINPID column is the process 
ID displayed by NT's Task Manager program. The TTY column gives which 
pseudo-terminal a process is running on, or a <literal>'?'</literal>
for services. The UID column shows which user owns each process. 
STIME is the time the process was started, and COMMAND gives the name
of the program running.
</para>

<para>
By default <command>ps</command> will only show processes owned by the
current user. With either the <literal>-a</literal> or <literal>-e</literal>
option, all user's processes (and system processes) are listed. There are
historical UNIX reasons for the synonomous options, which are functionally
identical. The <literal>-f</literal> option outputs a "full" listing with
usernames for UIDs. The <literal>-l</literal> option is the default display
mode, showing a "long" listing with all the above columns. The other display
option is <literal>-s</literal>, which outputs a shorter listing of just
PID, TTY, STIME, and COMMAND. The <literal>-u</literal> option allows you
to show only processes owned by a specific user. The <literal>-W</literal>
option causes <command>ps</command> show non-Cygwin Windows processes as 
well as Cygwin processes. The WINPID is also the PID, and they can be killed
with the Cygwin <command>kill</command> command's <literal>-f</literal>
option.
</para>

</sect2>

<sect2 id="regtool"><title>regtool</title>

<screen>
Usage: regtool.exe [OPTION] (add | check | get | list | remove | unset) KEY

Actions:
 add KEY\SUBKEY             add new SUBKEY
 check KEY                  exit 0 if KEY exists, 1 if not
 get KEY\VALUE              prints VALUE to stdout
 list KEY                   list SUBKEYs and VALUEs
 remove KEY                 remove KEY
 set KEY\VALUE [data ...]   set VALUE
 unset KEY\VALUE            removes VALUE from KEY

Options for 'list' Action:
 -k, --keys           print only KEYs
 -l, --list           print only VALUEs
 -p, --postfix        like ls -p, appends '\' postfix to KEY names

Options for 'set' Action:
 -e, --expand-string  set type to REG_EXPAND_SZ
 -i, --integer        set type to REG_DWORD
 -m, --multi-string   set type to REG_MULTI_SZ
 -s, --string         set type to REG_SZ

Other Options:
 -h, --help     output usage information and exit
 -q, --quiet    no error output, just nonzero return if KEY/VALUE missing
 -v, --verbose  verbose output, including VALUE contents when applicable
 -V, --version  output version information and exit

KEY is in the format [host]\prefix\KEY\KEY\VALUE, where host is optional
remote host in either \\hostname or hostname: format and prefix is any of:
  root     HKCR  HKEY_CLASSES_ROOT (local only)
  config   HKCC  HKEY_CURRENT_CONFIG (local only)
  user     HKCU  HKEY_CURRENT_USER (local only)
  machine  HKLM  HKEY_LOCAL_MACHINE
  users    HKU   HKEY_USERS

You can use forward slash ('/') as a separator instead of backslash, in
that case backslash is treated as escape character
Example: regtool.exe get '\user\software\Microsoft\Clock\iFormat'
</screen>

<para>The <command>regtool</command> program allows shell scripts
to access and modify the Windows registry.  Note that modifying the
Windows registry is dangerous, and carelessness here can result
in an unusable system.  Be careful.</para>

<para>The <literal>-v</literal> option means "verbose".  For most
commands, this causes additional or lengthier messages to be printed.
Conversely, the <literal>-q</literal> option supresses error messages,
so you can use the exit status of the program to detect if a key
exists or not (for example).</para>

<para>You must provide <command>regtool</command> with an 
<emphasis>action</emphasis> following options (if any). Currently,
the action must be <literal>add</literal>, <literal>set</literal>,
<literal>check</literal>, <literal>get</literal>, <literal>list</literal>,
<literal>remove</literal>, <literal>set</literal>, or <literal>unset</literal>.
</para>

<para>The <literal>add</literal> action adds a new key.  The 
<literal>check</literal> action checks to see if a key exists (the 
exit code of the program is zero if it does, nonzero if it does not).
The <literal>get</literal> action gets the value of a value of a key,
and prints it (and nothing else) to stdout.  Note: if the value
doesn't exist, an error message is printed and the program returns a
non-zero exit code.  If you give <literal>-q</literal>, it doesn't
print the message but does return the non-zero exit code.</para>

<para>
The <literal>list</literal> action lists the subkeys and values
belonging to the given key. With <literal>list</literal>, the 
<literal>-k</literal> option instructs <command>regtool</command>
to print only KEYs, and the <literal>-l</literal> option to print
only VALUEs. The <literal>-p</literal> option postfixes a 
<literal>'/'</literal> to each KEY, but leave VALUEs with no
postfix.  The <literal>remove</literal> action 
removes a key.  Note that you may need to remove everything in the key 
before you may remove it, but don't rely on this stopping you from 
accidentally removing too much.  
</para>

<para>The <literal>set</literal> action sets a value within a key.
<literal>-e</literal> means it's an expanding string (REG_EXPAND_SZ)
that contains embedded environment variables.  
<literal>-i</literal> means the value is an integer (REG_DWORD).
<literal>-m</literal> means it's a multi-string (REG_MULTI_SZ).  
<literal>-s</literal> means the value is a string (REG_SZ).
If you don't specify one of these, <command>regtool</command> tries to
guess the type based on the value you give.  If it looks like a
number, it's a DWORD.  If it starts with a percent, it's an expanding
string.  If you give multiple values, it's a multi-string.  Else, it's
a regular string.
The <literal>unset</literal> action removes a value from a key.
</para>

</sect2>

<sect2 id="setfacl"><title>setfacl</title>

<screen>
Usage: setfacl [-r] (-f ACL_FILE | -s acl_entries) FILE...
       setfacl [-r] ([-d acl_entries] [-m acl_entries]) FILE...

Modify file and directory access control lists (ACLs)

  -d, --delete     delete one or more specified ACL entries
  -f, --file       set ACL entries for FILE to ACL entries read
                   from a ACL_FILE
  -m, --modify     modify one or more specified ACL entries
  -r, --replace    replace mask entry with maximum permissions
                   needed for the file group class
  -s, --substitute substitute specified ACL entries for the
                   ACL of FILE
  -h, --help       output usage information and exit
  -v, --version    output version information and exit

At least one of (-d, -f, -m, -s) must be specified
</screen>

<para>
For each file given as parameter, <command>setfacl</command> will 
either replace its complete ACL (<literal>-s</literal>, <literal>-f</literal>), 
or it will add, modify, or delete ACL entries.
For more information on Cygwin and Windows ACLs, see
see <Xref Linkend="ntsec"> in the Cygwin User's Guide.
</para>

<para>
Acl_entries are one or more comma-separated ACL entries 
from the following list:
<screen>
         u[ser]::perm
         u[ser]:uid:perm
         g[roup]::perm
         g[roup]:gid:perm
         m[ask]::perm
         o[ther]::perm
</screen>
Default entries are like the above with the additional
default identifier. For example: 
<screen>
         d[efault]:u[ser]:uid:perm
</screen>
</para>

<para>
<emphasis>perm</emphasis> is either a 3-char permissions string in the form
"rwx" with the character <literal>'-'</literal> for no permission
or it is the octal representation of the permissions, a
value from 0 (equivalent to "---") to 7 ("rwx").
<emphasis>uid</emphasis> is a user name or a numerical uid.
<emphasis>gid</emphasis> is a group name or a numerical gid.
</para>

<para>
The following options are supported:
</para>

<para>
<literal>-d</literal>
Delete one or more specified entries from the file's ACL.
The owner, group and others entries must not be deleted.
Acl_entries to be deleted should be specified without
permissions, as in the following list:
<screen>
         u[ser]:uid
         g[roup]:gid
         d[efault]:u[ser]:uid
         d[efault]:g[roup]:gid
         d[efault]:m[ask]:
         d[efault]:o[ther]:
</screen>
</para>

<para>
<literal>-f</literal>
Take the Acl_entries from ACL_FILE one per line. Whitespace
characters are ignored, and the character "#" may be used
to start a comment.  The special filename "-" indicates
reading from stdin. Note that you can use this with 
<command>getfacl</command> and <command>setfacl</command> to copy 
ACLs from one file to another:
<screen>
$ getfacl source_file | setfacl -f - target_file
</screen>
</para>

<para>
Required entries are: 
one user entry for the owner of the file,
one group entry for the group of the file, and
one other entry.
</para>

<para>
If additional user and group entries are given:
a mask entry for the file group class of the file, and 
no duplicate user or group entries with the same uid/gid.
</para>

<para>
If it is a directory:
one default user entry for the owner of the file,
one default group entry for the group of the file,
one default mask entry for the file group class, and
one default other entry.