=head1 SYNOPSIS
-B<pts creategroup -name> <I<group name>>+ [-owner <I<owner of the group>>]
-[B<-id> <I<id (negated) for the group>>+] [B<-cell> <I<cell name>>]
- [B<-noauth>] [B<-force>] [-help]
-
-B<pts createg -na> <I<group name>>+ [-o <I<owner of the group>>]
-[B<-i> <I<id (negated) for the group>>+] [B<-c> <I<cell name>>]
- [B<-no>] [B<-f>] [-h]
+B<pts creategroup> B<-name> <I<group name>>+
+ [B<-owner> <I<owner of the group>>]
+ [B<-id> <I<id (negated) for the group>>+] [B<-cell> <I<cell name>>]
+ [B<-noauth>] [B<-force>] [B<-help>]
+
+B<pts createg> B<-na> <I<group name>>+ [B<-o> <I<owner of the group>>]
+ [B<-i> <I<id (negated) for the group>>+] [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
-B<pts cg -na> <I<group name>>+ [-o <I<owner of the group>>]
-[B<-i> <I<id (negated) for the group>>+]
- [B<-c> <I<cell name>>] [B<-no>] [B<-f>] [-h]
+B<pts cg> B<-na> <I<group name>>+ [B<-o> <I<owner of the group>>]
+ [B<-i> <I<id (negated) for the group>>+] [B<-c> <I<cell name>>]
+ [B<-no>] [B<-f>] [B<-h>]
=head1 DESCRIPTION
-The pts creategroup command creates an entry in the Protection
-Database for each group specified by the B<-name> argument. The
-entry records the issuer of the command as the group's creator, and as
-the group's owner unless the B<-owner> argument names an
-alternate user or group as the owner.
+The B<pts creategroup> command creates an entry in the Protection Database
+for each group specified by the B<-name> argument. The entry records the
+issuer of the command as the group's creator, and as the group's owner
+unless the B<-owner> argument names an alternate user or group as the
+owner.
There are two types of groups:
=item *
-I<regular>, the names of which have two parts separated by a
-colon. The part before the colon names the group's owner.
-Any user can create such groups.
-
+I<regular>, the names of which have two parts separated by a colon. The
+part before the colon names the group's owner. Any user can create such
+groups.
=item *
-I<prefix-less>, which do not have an owner prefix. Only
-members of the B<system:administrators> group can create
-prefix-less groups.
-
+I<prefix-less>, which do not have an owner prefix. Only members of the
+system:administrators group can create prefix-less groups.
=back
-Creating a group lowers the issuer's group-creation quota by
-one. This is true even if the B<-owner> argument is used to
-assign ownership to an alternate user or group. To display a
-user's group-creation quota, use the B<pts examine> command;
-to set it, use the B<pts setfields> command.
+Creating a group lowers the issuer's group-creation quota by one. This is
+true even if the B<-owner> argument is used to assign ownership to an
+alternate user or group. To display a user's group-creation quota, use the
+B<pts examine> command; to set it, use the B<pts setfields> command.
AFS group ID (AFS GID) numbers are negative integers and by default the
Protection Server assigns a GID that is one less (more negative) than the
-current value of the C<max group id> counter in the Protection
-Database, decrementing the counter by one for each group. Members of
-the B<system:administrators> group can use the B<-id>
-argument to assign specific AFS GID numbers. If any of the specified
-GIDs is lower (more negative) than the current value of the C<max group
-id> counter, the counter is reset to that value. It is acceptable
-to specify a GID greater (less negative) than the current value of the
-counter, but the creation operation fails if an existing group already has
-it. To display or set the value of the C<max group id> counter,
-use the B<pts listmax> or B<pts setmax> command,
-respectively.
+current value of the C<max group id> counter in the Protection Database,
+decrementing the counter by one for each group. Members of the
+system:administrators group can use the B<-id> argument to assign specific
+AFS GID numbers. If any of the specified GIDs is lower (more negative)
+than the current value of the C<max group id> counter, the counter is
+reset to that value. It is acceptable to specify a GID greater (less
+negative) than the current value of the counter, but the creation
+operation fails if an existing group already has it. To display or set the
+value of the C<max group id> counter, use the B<pts listmax> or B<pts
+setmax> command, respectively.
=head1 OUTPUT
The command generates the following string to confirm creation of each
group:
- group I<name> has id I<AFS GID>
+ group <name> has id <AFS GID>
-=head1 CAVEATS
+=head1 CAUTIONS
-Although using the -owner argument to designate a machine entry
-as a group's owner does not generate an error, it is not
-recommended. The Protection Server does not extend the usual privileges
-of group ownership to users logged onto the machine.
+Although using the B<-owner> argument to designate a machine entry as a
+group's owner does not generate an error, it is not recommended. The
+Protection Server does not extend the usual privileges of group ownership
+to users logged onto the machine.
=head1 OPTIONS
=over 4
-=item -name
+=item B<-name> <I<group name>>
-Specifies the name of each group to create. Provide a string of up
-to 63 characters, which can include lowercase (but not uppercase) letters,
+Specifies the name of each group to create. Provide a string of up to 63
+characters, which can include lowercase (but not uppercase) letters,
numbers, and punctuation marks. A regular name includes a single colon
-(B<:>) to separate the two parts of the name; the colon
-cannot appear in a prefix-less group name.
+(C<:>) to separate the two parts of the name; the colon cannot appear in a
+prefix-less group name.
A regular group's name must have the following format:
- I<owner_name>:I<group_name>
+ <owner_name>:<group_name>
-and the I<owner_name> field must reflect the actual owner of the
-group, as follows:
+and the <owner_name> field must reflect the actual owner of the group, as
+follows:
=over 4
=item *
-If the optional -owner argument is not included, the field must
-match the AFS username under which the issuer is currently
-authenticated.
-
+If the optional B<-owner> argument is not included, the field must match
+the AFS username under which the issuer is currently authenticated.
=item *
-If the -owner argument names an alternate AFS user, the field
-must match that AFS username.
-
+If the B<-owner> argument names an alternate AFS user, the field must
+match that AFS username.
=item *
-If the -owner argument names another regular group, the field
-must match the owning group's owner field (the part of its name before
-the colon). If the B<-owner> argument names a prefix-less
-group, the field must match the owning group's complete name.
-
+If the B<-owner> argument names another regular group, the field must
+match the owning group's owner field (the part of its name before the
+colon). If the B<-owner> argument names a prefix-less group, the field
+must match the owning group's complete name.
=back
-=item -owner
+=item B<-owner> <I<owner of the group>>
Specifies a user or group as the owner for each group, rather than the
issuer of the command. Provide either an AFS username or the name of a
-regular or prefix-less group. An owning group must already have at
-least one member. This requirement prevents assignment of
-self-ownership to a group during its creation; use the B<pts
-chown> command after issuing this command, if desired.
+regular or prefix-less group. An owning group must already have at least
+one member. This requirement prevents assignment of self-ownership to a
+group during its creation; use the B<pts chown> command after issuing this
+command, if desired.
-=item -id
+=item B<-id> <I<id for the group>>
Specifies a negative integer AFS GID number for each group, rather than
allowing the Protection Server to assign it. Precede the integer with a
-hyphen (B<->) to indicate that it is negative.
+hyphen (C<->) to indicate that it is negative.
-If this argument is used and the -name argument names multiple
-new groups, it is best to provide an equivalent number of AFS GIDs. The
-first GID is assigned to the first group, the second to the second group, and
-so on. If there are fewer GIDs than groups, the Protection Server
-assigns GIDs to the unmatched groups based on the C<max group id>
-counter. If there are more GIDs than groups, the excess GIDs are
-ignored. If any of the GIDs is lower (more negative) than the current
-value of the C<max group id> counter, the counter is reset to that
-value.
+If this argument is used and the B<-name> argument names multiple new
+groups, it is best to provide an equivalent number of AFS GIDs. The first
+GID is assigned to the first group, the second to the second group, and so
+on. If there are fewer GIDs than groups, the Protection Server assigns
+GIDs to the unmatched groups based on the C<max group id> counter. If
+there are more GIDs than groups, the excess GIDs are ignored. If any of
+the GIDs is lower (more negative) than the current value of the C<max
+group id> counter, the counter is reset to that value.
-=item -cell
+=item B<-cell> <I<cell name>>
Names the cell in which to run the command. For more details, see
-the introductory B<pts> reference page.
+L<pts(1)>.
-=item -noauth
+=item B<-noauth>
-Assigns the unprivileged identity anonymous to the
-issuer. For more details, see the introductory B<pts> reference
-page.
+Assigns the unprivileged identity anonymous to the issuer. For more
+details, see L<pts(1)>.
-=item -force
+=item B<-force>
Enables the command to continue executing as far as possible when errors
-or other problems occur, rather than halting execution at the first
-error.
+or other problems occur, rather than halting execution at the first error.
-=item -help
+=item B<-help>
-Prints the online help for this command. All other valid options
-are ignored.
+Prints the online help for this command. All other valid options are
+ignored.
=back
=head1 EXAMPLES
In the following example, the user pat creates groups called
-B<pat:friends> and B<pat:colleagues>.
+C<pat:friends> and C<pat:colleagues>.
% pts creategroup -name pat:friends pat:colleagues
-The following example shows a member of the
-B<system:administrators> group creating the prefix-less group
-B<staff> and assigning its ownership to the
-B<system:administrators> group rather than to herself.
+The following example shows a member of the system:administrators group
+creating the prefix-less group C<staff> and assigning its ownership to the
+system:administrators group rather than to herself.
% pts creategroup -name staff -owner system:administrators
In the following example, the user pat creates a group called
-B<smith:team-members>, which is allowed because the
-B<-owner> argument specifies the required value
-(B<smith>).
+C<smith:team-members>, which is allowed because the B<-owner> argument
+specifies the required value (C<smith>).
% pts creategroup -name smith:team-members -owner smith
=head1 PRIVILEGE REQUIRED
-The issuer must belong to the system:administrators group
-to create prefix-less groups or include the B<-id> argument.
+The issuer must belong to the system:administrators group to create
+prefix-less groups or include the B<-id> argument.
To create a regular group, the issuer must
=item *
-Be authenticated. The command fails if the -noauth flag
-is provided.
-
+Be authenticated. The command fails if the B<-noauth> flag is provided.
=item *
-Have a group-creation quota greater than zero. The pts
-examine command displays this quota.
-
+Have a group-creation quota greater than zero. The B<pts examine> command
+displays this quota.
=back