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 | .\" |
ae59e04c | 6 | .\" @(#)getgrent.3 6.7 (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 , | |
16 | .Nm setgrfile , | |
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 * | |
25 | .Fn getgrname "const char *name" | |
26 | .Ft struct group * | |
27 | .Fn getgrgid "gid_t gid" | |
28 | .Ft struct group * | |
29 | .Fn setgroupent "int stayopen" | |
30 | .Ft void | |
31 | .Fn setgrfile "const char *name" | |
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 | |
76 | .Fn setgrfile | |
77 | function | |
78 | changes the default group file to | |
79 | .Fa file , | |
80 | thus allowing the use of alternate group files. | |
81 | .Pp | |
82 | The | |
83 | .Fn setgroupent | |
84 | function | |
2f931ec6 | 85 | opens the file, or rewinds it if it is already open. If |
ae59e04c | 86 | .Fa stayopen |
2f931ec6 | 87 | is non-zero, file descriptors are left open, significantly speeding |
ae59e04c CL |
88 | functions subsequent calls. This functionality is unnecessary for |
89 | .Fn getgrent | |
2f931ec6 KB |
90 | as it doesn't close its file descriptors by default. It should also |
91 | be noted that it is dangerous for long-running programs to use this | |
92 | functionality as the group file may be updated. | |
ae59e04c CL |
93 | .Pp |
94 | The | |
95 | .Fn setgrent | |
96 | function | |
2f931ec6 | 97 | is identical to |
ae59e04c | 98 | .Fn setgroupent |
2f931ec6 | 99 | with an argument of zero. |
ae59e04c CL |
100 | .Pp |
101 | The | |
102 | .Fn endgrent | |
103 | function | |
62ab31a2 | 104 | closes any open files. |
ae59e04c CL |
105 | .Sh RETURN VALUES |
106 | The functions | |
107 | .Fn getgrent , | |
108 | .Fn getgrnam , | |
109 | and | |
110 | .Fn getgrgid , | |
111 | return a pointer to the group entry if successful; if end-of-file | |
112 | is reached or an error occurs a null pointer is returned. | |
113 | The functions | |
114 | .Fn setgroupent | |
115 | and | |
116 | .Fn setgrent | |
117 | return the value 1 if successful, otherwise the value | |
118 | 0 is returned. | |
119 | The functions | |
120 | .Fn endgrent | |
121 | and | |
122 | .Fn setgrfile | |
123 | have no return value. | |
124 | .Sh FILES | |
125 | .Bl -tag -width /etc/group -compact | |
126 | .It Pa /etc/group | |
127 | group database file | |
128 | .El | |
129 | .Sh SEE ALSO | |
130 | .Fn getpwent 3 , | |
131 | .Fn group 5 | |
132 | .Sh HISTORY | |
133 | The functions | |
134 | .Fn endgrent , | |
135 | .Fn getgrent , | |
136 | .Fn getgrnam , | |
137 | .Fn getgrgid , | |
138 | and | |
139 | .Fn setgrent | |
140 | appeared in | |
141 | .At v7 . | |
142 | The functions | |
143 | .Fn setgrfile | |
2f931ec6 | 144 | and |
ae59e04c CL |
145 | .Fn setgroupent |
146 | appeared in | |
147 | .Bx 4.3 Reno . | |
148 | .Sh BUGS | |
149 | The functions | |
150 | .Fn getgrent , | |
151 | .Fn getgrnam , | |
152 | .Fn getgrgid , | |
153 | .Fn setgroupent | |
2f931ec6 | 154 | and |
ae59e04c CL |
155 | .Fn setgrent |
156 | leave their results in an internal static object and return | |
157 | a pointer to that object. Subsequent calls to | |
158 | the same function | |
159 | will modify the same object. | |
160 | .Pp | |
161 | The functions | |
162 | .Fn getgrent , | |
163 | .Fn endgrent , | |
164 | .Fn setgroupent , | |
2f931ec6 | 165 | and |
ae59e04c | 166 | .Fn setgrent |
2f931ec6 KB |
167 | are fairly useless in a networked environment and should be |
168 | avoided, if possible. |