Commit | Line | Data |
---|---|---|
ae59e04c CL |
1 | .\" Copyright (c) 1989, 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
62ab31a2 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
2f931ec6 | 5 | .\" |
f42813ad | 6 | .\" @(#)getgrent.3 6.9 (Berkeley) %G% |
6c9d675c | 7 | .\" |
ae59e04c CL |
8 | .Dd |
9 | .Dt GETGRENT 3 | |
10 | .Os | |
11 | .Sh NAME | |
12 | .Nm getgrent , | |
13 | .Nm getgrnam , | |
14 | .Nm getgrgid , | |
15 | .Nm setgroupent , | |
d5001484 | 16 | .\" .Nm setgrfile , |
ae59e04c CL |
17 | .Nm setgrent , |
18 | .Nm endgrent | |
19 | .Nd group database operations | |
20 | .Sh SYNOPSIS | |
21 | .Fd #include <grp.h> | |
22 | .Ft struct group * | |
23 | .Fn getgrent void | |
24 | .Ft struct group * | |
f42813ad | 25 | .Fn getgrnam "const char *name" |
ae59e04c CL |
26 | .Ft struct group * |
27 | .Fn getgrgid "gid_t gid" | |
28 | .Ft struct group * | |
29 | .Fn setgroupent "int stayopen" | |
d5001484 CL |
30 | .\" .Ft void |
31 | .\" .Fn setgrfile "const char *name" | |
ae59e04c CL |
32 | .Ft int |
33 | .Fn setgrent void | |
34 | .Ft void | |
35 | .Fn endgrent void | |
36 | .Sh DESCRIPTION | |
37 | These functions operate on the group database file | |
38 | .Pa /etc/group | |
39 | which is described | |
40 | in | |
41 | .Xr group 5 . | |
42 | Each line of the database is defined by the structure | |
43 | .Ar group | |
44 | found in the include | |
2f931ec6 | 45 | file |
ae59e04c CL |
46 | .Aq Pa grp.h : |
47 | .Bd -literal -offset indent | |
2f931ec6 | 48 | struct group { |
ae59e04c CL |
49 | char *gr_name; /* group name */ |
50 | char *gr_passwd; /* group password */ | |
2f931ec6 | 51 | gid_t gr_gid; /* group id */ |
ae59e04c | 52 | char **gr_mem; /* group members */ |
62ab31a2 | 53 | }; |
ae59e04c CL |
54 | .Ed |
55 | .Pp | |
56 | The functions | |
57 | .Fn getgrnam | |
2f931ec6 | 58 | and |
ae59e04c CL |
59 | .Fn getgrgid |
60 | search the group database for the given group name pointed to by | |
61 | .Ar name | |
62 | or the group id pointed to by | |
63 | .Ar gid , | |
2f931ec6 KB |
64 | respectively, returning the first one encountered. Identical group |
65 | names or group gids may result in undefined behavior. | |
ae59e04c CL |
66 | .Pp |
67 | The | |
68 | .Fn getgrent | |
69 | function | |
2f931ec6 KB |
70 | sequentially reads the group database and is intended for programs |
71 | that wish to step through the complete list of groups. | |
ae59e04c | 72 | .Pp |
2f931ec6 | 73 | All three routines will open the group file for reading, if necesssary. |
ae59e04c CL |
74 | .Pp |
75 | The | |
ae59e04c CL |
76 | .Fn setgroupent |
77 | function | |
2f931ec6 | 78 | opens the file, or rewinds it if it is already open. If |
ae59e04c | 79 | .Fa stayopen |
2f931ec6 | 80 | is non-zero, file descriptors are left open, significantly speeding |
ae59e04c CL |
81 | functions subsequent calls. This functionality is unnecessary for |
82 | .Fn getgrent | |
2f931ec6 KB |
83 | as it doesn't close its file descriptors by default. It should also |
84 | be noted that it is dangerous for long-running programs to use this | |
85 | functionality as the group file may be updated. | |
ae59e04c CL |
86 | .Pp |
87 | The | |
88 | .Fn setgrent | |
89 | function | |
2f931ec6 | 90 | is identical to |
ae59e04c | 91 | .Fn setgroupent |
2f931ec6 | 92 | with an argument of zero. |
ae59e04c CL |
93 | .Pp |
94 | The | |
95 | .Fn endgrent | |
96 | function | |
62ab31a2 | 97 | closes any open files. |
ae59e04c CL |
98 | .Sh RETURN VALUES |
99 | The functions | |
100 | .Fn getgrent , | |
101 | .Fn getgrnam , | |
102 | and | |
103 | .Fn getgrgid , | |
104 | return a pointer to the group entry if successful; if end-of-file | |
105 | is reached or an error occurs a null pointer is returned. | |
106 | The functions | |
107 | .Fn setgroupent | |
108 | and | |
109 | .Fn setgrent | |
110 | return the value 1 if successful, otherwise the value | |
111 | 0 is returned. | |
112 | The functions | |
113 | .Fn endgrent | |
114 | and | |
115 | .Fn setgrfile | |
116 | have no return value. | |
117 | .Sh FILES | |
118 | .Bl -tag -width /etc/group -compact | |
119 | .It Pa /etc/group | |
120 | group database file | |
121 | .El | |
122 | .Sh SEE ALSO | |
123 | .Fn getpwent 3 , | |
124 | .Fn group 5 | |
125 | .Sh HISTORY | |
126 | The functions | |
127 | .Fn endgrent , | |
128 | .Fn getgrent , | |
129 | .Fn getgrnam , | |
130 | .Fn getgrgid , | |
131 | and | |
132 | .Fn setgrent | |
133 | appeared in | |
134 | .At v7 . | |
135 | The functions | |
136 | .Fn setgrfile | |
2f931ec6 | 137 | and |
ae59e04c CL |
138 | .Fn setgroupent |
139 | appeared in | |
140 | .Bx 4.3 Reno . | |
d5001484 CL |
141 | .Sh COMPATIBILITY |
142 | The historic function | |
143 | .Fn setgrfile , | |
144 | which allowed the specification of alternate password databases, has | |
145 | been deprecated and is no longer available. | |
ae59e04c CL |
146 | .Sh BUGS |
147 | The functions | |
148 | .Fn getgrent , | |
149 | .Fn getgrnam , | |
150 | .Fn getgrgid , | |
151 | .Fn setgroupent | |
2f931ec6 | 152 | and |
ae59e04c CL |
153 | .Fn setgrent |
154 | leave their results in an internal static object and return | |
155 | a pointer to that object. Subsequent calls to | |
156 | the same function | |
157 | will modify the same object. | |
158 | .Pp | |
159 | The functions | |
160 | .Fn getgrent , | |
161 | .Fn endgrent , | |
162 | .Fn setgroupent , | |
2f931ec6 | 163 | and |
ae59e04c | 164 | .Fn setgrent |
2f931ec6 KB |
165 | are fairly useless in a networked environment and should be |
166 | avoided, if possible. |