Partially revert r367756 (chpass(1) synopsis changes)

[pw-darwin.git] / pw / pw.8

diff --git a/pw/pw.8 b/pw/pw.8
index 3a9c0b0b87b9fdf1fe3e7011d8b12dbe81c03f32..18930fbf22855f7c05b5f28548061bb3e2487ba7 100644 (file)
--- a/pw/pw.8
+++ b/pw/pw.8
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 14, 2015
+.Dd February 8, 2019
 .Dt PW 8
 .Os
 .Sh NAME
@@ -420,18 +420,16 @@ Set the account's primary group to the given group.
 .Ar group
 may be defined by either its name or group number.
 .It Fl G Ar grouplist
-Set additional group memberships for an account.
+Set secondary group memberships for an account.
 .Ar grouplist
-is a comma, space or tab-separated list of group names or group numbers.
-The user's name is added to the group lists in
-.Pa /etc/group ,
-and
-removed from any groups not specified in
-.Ar grouplist .
-Note: a user should not be added to their primary group with
+is a comma, space, or tab-separated list of group names or group numbers.
+The user is added to the groups specified in
+.Ar grouplist ,
+and removed from all groups not specified.
+The current login session is not affected by group membership changes,
+which only take effect when the user reconnects.
+Note: do not add a user to their primary group with
 .Ar grouplist .
-Also, group membership changes do not take effect for current user login
-sessions, requiring the user to reconnect to be affected by the changes.
 .It Fl L Ar class
 This option sets the login class for the user being created.
 See
@@ -613,6 +611,14 @@ that the account expires.
 A value of 0 suppresses automatic calculation of the expiry date.
 .It Fl p Ar days
 Set the default password expiration period in days.
+When
+.Fl D
+is used, the
+.Ar days
+argument is interpreted differently.
+It must be numeric and represents the number of days after creation
+that the account expires.
+A value of 0 suppresses automatic calculation of the expiry date.
 .It Fl g Ar group
 Set the default group for new users.
 If a blank group is specified using
@@ -956,6 +962,29 @@ Pw default options file
 .It Pa /var/log/userlog
 User/group modification logfile
 .El
+.Sh EXAMPLES
+Add new user Glurmo Smith (gsmith).
+A gsmith login group is created if not already present.
+The login shell is set to
+.Xr csh 1 .
+A new home directory at
+.Pa /home/gsmith
+is created if it does not already exist.
+Finally, a random password is generated and displayed:
+.Bd -literal -offset indent
+pw useradd -n gsmith -c "Glurmo Smith" -s /bin/csh -m -w random
+.Ed
+.Pp
+Delete the gsmith user and their home directory, including contents.
+.Bd -literal -offset indent
+pw userdel -n gsmith -r
+.Ed
+.Pp
+Add the existing user jsmith to the wheel group,
+in addition to the other groups jsmith is already a member of.
+.Bd -literal -offset indent
+pw groupmod wheel -m jsmith
+.Ed
 .Sh EXIT STATUS
 The
 .Nm