Commit | Line | Data |
---|---|---|
2f931ec6 KB |
1 | .\" Copyright (c) 1989 The Regents of the University of California. |
2 | .\" All rights reserved. | |
62ab31a2 | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
2f931ec6 | 5 | .\" |
91cff1e1 | 6 | .\" @(#)getgrent.3 6.5 (Berkeley) %G% |
6c9d675c | 7 | .\" |
6548329e | 8 | .TH GETGRENT 3 "" |
6c9d675c KM |
9 | .AT 3 |
10 | .SH NAME | |
2f931ec6 KB |
11 | getgrent, getgrnam, getgrgid, setgroupent, setgrfile, setgrent, |
12 | endgrent \- get group file entry | |
6c9d675c KM |
13 | .SH SYNOPSIS |
14 | .nf | |
15 | .B #include <grp.h> | |
16 | .PP | |
17 | .B struct group *getgrent() | |
18 | .PP | |
2f931ec6 KB |
19 | .B struct group *getgrnam(name) |
20 | .B char *name; | |
21 | .PP | |
6c9d675c | 22 | .B struct group *getgrgid(gid) |
62ab31a2 | 23 | .B gid_t gid; |
6c9d675c | 24 | .PP |
2f931ec6 KB |
25 | .B setgroupent(stayopen) |
26 | .B int stayopen; | |
27 | .PP | |
28 | .B void setgrfile(name) | |
6c9d675c KM |
29 | .B char *name; |
30 | .PP | |
31 | .B setgrent() | |
32 | .PP | |
62ab31a2 | 33 | .B void endgrent() |
6c9d675c KM |
34 | .fi |
35 | .SH DESCRIPTION | |
36 | .I Getgrent, | |
37 | .I getgrgid | |
38 | and | |
39 | .I getgrnam | |
2f931ec6 KB |
40 | each return a pointer to a structure containing the broken-out fields |
41 | of a line in the group file. This structure is defined by the include | |
42 | file | |
43 | .IR < grp.h >, | |
44 | and contains the following fields: | |
6c9d675c | 45 | .PP |
2f931ec6 | 46 | .RS |
6c9d675c | 47 | .nf |
2f931ec6 KB |
48 | struct group { |
49 | char *gr_name; /* group name */ | |
50 | char *gr_passwd; /* group password */ | |
51 | gid_t gr_gid; /* group id */ | |
52 | char **gr_mem; /* group members */ | |
62ab31a2 KB |
53 | }; |
54 | .ft R | |
55 | .ad | |
6c9d675c KM |
56 | .fi |
57 | .RE | |
58 | .PP | |
2f931ec6 KB |
59 | These fields are more completely described in |
60 | .IR group (5). | |
61 | .PP | |
62 | .I Getgrnam | |
63 | and | |
64 | .I getgrgid | |
65 | search the group database for a matching group name or group id, | |
66 | respectively, returning the first one encountered. Identical group | |
67 | names or group gids may result in undefined behavior. | |
68 | .PP | |
69 | .I Getgrent | |
70 | sequentially reads the group database and is intended for programs | |
71 | that wish to step through the complete list of groups. | |
72 | .PP | |
73 | All three routines will open the group file for reading, if necesssary. | |
6c9d675c | 74 | .PP |
62ab31a2 KB |
75 | .I Setgrfile |
76 | changes the default group file to | |
2f931ec6 KB |
77 | .IR file , |
78 | thus allowing the use of alternate group files. | |
79 | .PP | |
80 | .I Setgroupent | |
81 | opens the file, or rewinds it if it is already open. If | |
82 | .I stayopen | |
83 | is non-zero, file descriptors are left open, significantly speeding | |
84 | up subsequent calls. This functionality is unnecessary for | |
85 | .I getgrent | |
86 | as it doesn't close its file descriptors by default. It should also | |
87 | be noted that it is dangerous for long-running programs to use this | |
88 | functionality as the group file may be updated. | |
62ab31a2 KB |
89 | .PP |
90 | .I Setgrent | |
2f931ec6 KB |
91 | is identical to |
92 | .I setgroupent | |
93 | with an argument of zero. | |
62ab31a2 KB |
94 | .PP |
95 | .I Endgrent | |
96 | closes any open files. | |
97 | .PP | |
6c9d675c | 98 | .PP |
6c9d675c KM |
99 | .SH FILES |
100 | /etc/group | |
101 | .SH "SEE ALSO" | |
2f931ec6 | 102 | getpwent(3), group(5) |
6c9d675c | 103 | .SH DIAGNOSTICS |
62ab31a2 KB |
104 | The routines |
105 | .IR getgrent , | |
62ab31a2 | 106 | .IR getgrnam , |
2f931ec6 KB |
107 | and |
108 | .IR getgrgid , | |
109 | return a null pointer on EOF or error. | |
110 | .I Setgroupent | |
111 | and | |
112 | .I setgrent | |
113 | return 0 on failure, 1 on success. | |
62ab31a2 KB |
114 | .I Endgrent |
115 | and | |
116 | .I setgrfile | |
117 | have no return value. | |
6c9d675c | 118 | .SH BUGS |
2f931ec6 KB |
119 | All information is contained in a static buffer which is overwritten |
120 | by each new call. It must be copied elsewhere to be retained. | |
121 | .PP | |
122 | The routines | |
123 | .IR getgrent , | |
124 | .IR endgrent , | |
125 | .IR setgroupent , | |
126 | and | |
127 | .IR setgrent | |
128 | are fairly useless in a networked environment and should be | |
129 | avoided, if possible. |