Upgrade to libarchive 2.0.28 giving us ar support and a new manpage.
[dragonfly.git] / share / man / man5 / group.5
CommitLineData
984263bc
MD
1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" From: @(#)group.5 8.3 (Berkeley) 4/19/94
33.\" $FreeBSD: src/share/man/man5/group.5,v 1.15.2.4 2002/02/01 15:51:18 ru Exp $
44cb301e 34.\" $DragonFly: src/share/man/man5/group.5,v 1.5 2006/05/26 19:39:40 swildner Exp $
984263bc
MD
35.\"
36.Dd September 29, 1994
37.Dt GROUP 5
38.Os
39.Sh NAME
40.Nm group
41.Nd format of the group permissions file
42.Sh DESCRIPTION
43The file
44.Aq Pa /etc/group
45consists of newline separated
46.Tn ASCII
47records, one per group, containing four colon
48.Ql \&:
49separated fields.
50These fields are as follows:
51.Bl -tag -width password -offset indent -compact
52.It group
53Name of the group.
54.It passwd
55Group's
56.Em encrypted
57password.
58.It gid
59The group's decimal ID.
60.It member
61Group members.
62.El
63.Pp
64Lines whose first non-whitespace character is a pound-sign (#)
65are comments, and are ignored.
66Blank lines that consist
67only of spaces, tabs or newlines are also ignored.
68.Pp
69The
70.Ar group
71field is the group name used for granting file access to users
72who are members of the group.
73The
74.Ar gid
75field is the number associated with the group name.
76They should both be unique across the system (and often
77across a group of systems) since they control file access.
78The
79.Ar passwd
80field
81is an optional
82.Em encrypted
83password.
84This field is rarely used
85and an asterisk is normally placed in it rather than leaving it blank.
86The
87.Ar member
88field contains the names of users granted the privileges of
89.Ar group .
90The member names are separated by commas without spaces or newlines.
91A user is automatically in a group if that group was specified
92in their
93.Pa /etc/passwd
94entry and does not need to be added to that group in the
95.Pa /etc/group file.
96.\" .Pp
97.\" When the system reads the file
98.\" .Pa /etc/group
99.\" the fields are read into the structure
100.\" .Fa group
101.\" declared in
44cb301e 102.\" .In grp.h :
984263bc
MD
103.\" .Bd -literal -offset indent
104.\" struct group {
105.\" char *gr_name; /* group name */
106.\" char *gr_passwd; /* group password */
107.\" int gr_gid; /* group id */
108.\" char **gr_mem; /* group members */
109.\" };
110.\" .Ed
111.Sh YP/NIS INTERACTION
112The
113.Pa /etc/group
114file can be configured to enable the YP/NIS group database.
115An entry whose
116.Ar name
117field consists of a plus sign (`+') followed by a group name, will be
118replaced internally to the C library with the YP/NIS group entry for the
119named group. An entry whose
120.Ar name
121field consists of a single plus sign with no group name following,
122will be replaced with the entire YP/NIS
123.Dq Li group.byname
124map.
125.Pp
126If the YP/NIS group database is enabled for any reason, all reverse
127lookups (i.e.,
128.Fn getgrgid )
129will use the entire database, even if only a few groups are enabled.
130Thus, the group name returned by
131.Fn getgrgid
132is not guaranteed to have a valid forward mapping.
133.Sh LIMITS
134There are various limitations which are explained in
135the function where they occur; see section
136.Sx SEE ALSO .
137.Pp
138In older implementations,
139a group cannot have more than 200 members.
140The maximum line length of
141.Pa /etc/group
142is 1024 characters.
143Longer lines will be skipped.
144This limitation disappeared in
145.Fx 3.0 .
146Older binaries that are statically linked, depend on old
147shared libraries, or
9bb2a92d 148.No non- Ns Dx
984263bc
MD
149binaries in compatibility mode
150may still have this limits.
151.Sh FILES
152.Bl -tag -width /etc/group -compact
153.It Pa /etc/group
154.El
155.Sh SEE ALSO
156.Xr passwd 1 ,
157.Xr setgroups 2 ,
158.Xr crypt 3 ,
159.Xr getgrent 3 ,
160.Xr initgroups 3 ,
161.Xr passwd 5 ,
162.Xr yp 8
984263bc
MD
163.Sh HISTORY
164A
165.Nm
166file format appeared in
167.At v6 .
168The YP/NIS functionality is modeled after
169.Tn SunOS
170and first appeared in
171.Fx 1.1 .
172Support for comments first appeared in
173.Fx 3.0 .
ac561d34
SW
174.Sh BUGS
175The
176.Xr passwd 1
177command does not change the
178.Nm
179passwords.