]>
Commit | Line | Data |
---|---|---|
ba1ffaa1 | 1 | @node Users and Groups |
28f540f4 RM |
2 | @chapter Users and Groups |
3 | ||
4 | Every user who can log in on the system is identified by a unique number | |
5 | called the @dfn{user ID}. Each process has an effective user ID which | |
6 | says which user's access permissions it has. | |
7 | ||
8 | Users are classified into @dfn{groups} for access control purposes. Each | |
9 | process has one or more @dfn{group ID values} which say which groups the | |
10 | process can use for access to files. | |
11 | ||
12 | The effective user and group IDs of a process collectively form its | |
13 | @dfn{persona}. This determines which files the process can access. | |
14 | Normally, a process inherits its persona from the parent process, but | |
15 | under special circumstances a process can change its persona and thus | |
16 | change its access permissions. | |
17 | ||
18 | Each file in the system also has a user ID and a group ID. Access | |
19 | control works by comparing the user and group IDs of the file with those | |
20 | of the running process. | |
21 | ||
22 | The system keeps a database of all the registered users, and another | |
23 | database of all the defined groups. There are library functions you | |
24 | can use to examine these databases. | |
25 | ||
26 | @menu | |
27 | * User and Group IDs:: Each user has a unique numeric ID; | |
28 | likewise for groups. | |
29 | * Process Persona:: The user IDs and group IDs of a process. | |
30 | * Why Change Persona:: Why a program might need to change | |
31 | its user and/or group IDs. | |
32 | * How Change Persona:: Changing the user and group IDs. | |
33 | * Reading Persona:: How to examine the user and group IDs. | |
34 | ||
35 | * Setting User ID:: Functions for setting the user ID. | |
36 | * Setting Groups:: Functions for setting the group IDs. | |
37 | ||
38 | * Enable/Disable Setuid:: Turning setuid access on and off. | |
39 | * Setuid Program Example:: The pertinent parts of one sample program. | |
40 | * Tips for Setuid:: How to avoid granting unlimited access. | |
41 | ||
42 | * Who Logged In:: Getting the name of the user who logged in, | |
43 | or of the real user ID of the current process. | |
44 | ||
0413b54c UD |
45 | * User Accounting Database:: Keeping information about users and various |
46 | actions in databases. | |
47 | ||
28f540f4 RM |
48 | * User Database:: Functions and data structures for |
49 | accessing the user database. | |
50 | * Group Database:: Functions and data structures for | |
51 | accessing the group database. | |
ba1ffaa1 | 52 | * Netgroup Database:: Functions for accessing the netgroup database. |
28f540f4 RM |
53 | * Database Example:: Example program showing use of database |
54 | inquiry functions. | |
55 | @end menu | |
56 | ||
0413b54c | 57 | @node User and Group IDs |
28f540f4 RM |
58 | @section User and Group IDs |
59 | ||
60 | @cindex login name | |
61 | @cindex user name | |
62 | @cindex user ID | |
63 | Each user account on a computer system is identified by a @dfn{user | |
64 | name} (or @dfn{login name}) and @dfn{user ID}. Normally, each user name | |
65 | has a unique user ID, but it is possible for several login names to have | |
66 | the same user ID. The user names and corresponding user IDs are stored | |
67 | in a data base which you can access as described in @ref{User Database}. | |
68 | ||
69 | @cindex group name | |
70 | @cindex group ID | |
71 | Users are classified in @dfn{groups}. Each user name also belongs to | |
72 | one or more groups, and has one @dfn{default group}. Users who are | |
73 | members of the same group can share resources (such as files) that are | |
74 | not accessible to users who are not a member of that group. Each group | |
75 | has a @dfn{group name} and @dfn{group ID}. @xref{Group Database}, | |
76 | for how to find information about a group ID or group name. | |
77 | ||
0413b54c | 78 | @node Process Persona |
28f540f4 RM |
79 | @section The Persona of a Process |
80 | @cindex persona | |
81 | @cindex effective user ID | |
82 | @cindex effective group ID | |
83 | ||
84 | @c !!! bogus; not single ID. set of effective group IDs (and, in GNU, | |
85 | @c set of effective UIDs) determines privilege. lying here and then | |
86 | @c telling the truth below is confusing. | |
87 | At any time, each process has a single user ID and a group ID which | |
88 | determine the privileges of the process. These are collectively called | |
89 | the @dfn{persona} of the process, because they determine ``who it is'' | |
90 | for purposes of access control. These IDs are also called the | |
91 | @dfn{effective user ID} and @dfn{effective group ID} of the process. | |
92 | ||
93 | Your login shell starts out with a persona which consists of your user | |
706074a5 | 94 | ID and your default group ID. |
28f540f4 RM |
95 | @c !!! also supplementary group IDs. |
96 | In normal circumstances, all your other processes inherit these values. | |
97 | ||
98 | @cindex real user ID | |
99 | @cindex real group ID | |
100 | A process also has a @dfn{real user ID} which identifies the user who | |
101 | created the process, and a @dfn{real group ID} which identifies that | |
102 | user's default group. These values do not play a role in access | |
103 | control, so we do not consider them part of the persona. But they are | |
104 | also important. | |
105 | ||
106 | Both the real and effective user ID can be changed during the lifetime | |
107 | of a process. @xref{Why Change Persona}. | |
108 | ||
109 | @cindex supplementary group IDs | |
110 | In addition, a user can belong to multiple groups, so the persona | |
111 | includes @dfn{supplementary group IDs} that also contribute to access | |
112 | permission. | |
113 | ||
114 | For details on how a process's effective user IDs and group IDs affect | |
115 | its permission to access files, see @ref{Access Permission}. | |
116 | ||
117 | The user ID of a process also controls permissions for sending signals | |
118 | using the @code{kill} function. @xref{Signaling Another Process}. | |
119 | ||
0413b54c | 120 | @node Why Change Persona |
28f540f4 RM |
121 | @section Why Change the Persona of a Process? |
122 | ||
123 | The most obvious situation where it is necessary for a process to change | |
124 | its user and/or group IDs is the @code{login} program. When | |
125 | @code{login} starts running, its user ID is @code{root}. Its job is to | |
126 | start a shell whose user and group IDs are those of the user who is | |
127 | logging in. (To accomplish this fully, @code{login} must set the real | |
128 | user and group IDs as well as its persona. But this is a special case.) | |
129 | ||
130 | The more common case of changing persona is when an ordinary user | |
131 | program needs access to a resource that wouldn't ordinarily be | |
132 | accessible to the user actually running it. | |
133 | ||
134 | For example, you may have a file that is controlled by your program but | |
135 | that shouldn't be read or modified directly by other users, either | |
136 | because it implements some kind of locking protocol, or because you want | |
137 | to preserve the integrity or privacy of the information it contains. | |
138 | This kind of restricted access can be implemented by having the program | |
139 | change its effective user or group ID to match that of the resource. | |
140 | ||
141 | Thus, imagine a game program that saves scores in a file. The game | |
142 | program itself needs to be able to update this file no matter who is | |
143 | running it, but if users can write the file without going through the | |
144 | game, they can give themselves any scores they like. Some people | |
145 | consider this undesirable, or even reprehensible. It can be prevented | |
146 | by creating a new user ID and login name (say, @code{games}) to own the | |
147 | scores file, and make the file writable only by this user. Then, when | |
148 | the game program wants to update this file, it can change its effective | |
149 | user ID to be that for @code{games}. In effect, the program must | |
150 | adopt the persona of @code{games} so it can write the scores file. | |
151 | ||
0413b54c | 152 | @node How Change Persona |
28f540f4 RM |
153 | @section How an Application Can Change Persona |
154 | @cindex @code{setuid} programs | |
155 | ||
156 | The ability to change the persona of a process can be a source of | |
157 | unintentional privacy violations, or even intentional abuse. Because of | |
158 | the potential for problems, changing persona is restricted to special | |
159 | circumstances. | |
160 | ||
161 | You can't arbitrarily set your user ID or group ID to anything you want; | |
162 | only privileged processes can do that. Instead, the normal way for a | |
163 | program to change its persona is that it has been set up in advance to | |
164 | change to a particular user or group. This is the function of the setuid | |
165 | and setgid bits of a file's access mode. @xref{Permission Bits}. | |
166 | ||
167 | When the setuid bit of an executable file is set, executing that file | |
168 | automatically changes the effective user ID to the user that owns the | |
169 | file. Likewise, executing a file whose setgid bit is set changes the | |
170 | effective group ID to the group of the file. @xref{Executing a File}. | |
171 | Creating a file that changes to a particular user or group ID thus | |
172 | requires full access to that user or group ID. | |
173 | ||
174 | @xref{File Attributes}, for a more general discussion of file modes and | |
175 | accessibility. | |
176 | ||
177 | A process can always change its effective user (or group) ID back to its | |
178 | real ID. Programs do this so as to turn off their special privileges | |
179 | when they are not needed, which makes for more robustness. | |
180 | ||
181 | @c !!! talk about _POSIX_SAVED_IDS | |
182 | ||
0413b54c | 183 | @node Reading Persona |
28f540f4 RM |
184 | @section Reading the Persona of a Process |
185 | ||
186 | Here are detailed descriptions of the functions for reading the user and | |
187 | group IDs of a process, both real and effective. To use these | |
188 | facilities, you must include the header files @file{sys/types.h} and | |
189 | @file{unistd.h}. | |
190 | @pindex unistd.h | |
191 | @pindex sys/types.h | |
192 | ||
193 | @comment sys/types.h | |
194 | @comment POSIX.1 | |
195 | @deftp {Data Type} uid_t | |
196 | This is an integer data type used to represent user IDs. In the GNU | |
197 | library, this is an alias for @code{unsigned int}. | |
198 | @end deftp | |
199 | ||
200 | @comment sys/types.h | |
201 | @comment POSIX.1 | |
202 | @deftp {Data Type} gid_t | |
203 | This is an integer data type used to represent group IDs. In the GNU | |
204 | library, this is an alias for @code{unsigned int}. | |
205 | @end deftp | |
206 | ||
207 | @comment unistd.h | |
208 | @comment POSIX.1 | |
209 | @deftypefun uid_t getuid (void) | |
210 | The @code{getuid} function returns the real user ID of the process. | |
211 | @end deftypefun | |
212 | ||
213 | @comment unistd.h | |
214 | @comment POSIX.1 | |
215 | @deftypefun gid_t getgid (void) | |
216 | The @code{getgid} function returns the real group ID of the process. | |
217 | @end deftypefun | |
218 | ||
219 | @comment unistd.h | |
220 | @comment POSIX.1 | |
221 | @deftypefun uid_t geteuid (void) | |
222 | The @code{geteuid} function returns the effective user ID of the process. | |
223 | @end deftypefun | |
224 | ||
225 | @comment unistd.h | |
226 | @comment POSIX.1 | |
227 | @deftypefun gid_t getegid (void) | |
228 | The @code{getegid} function returns the effective group ID of the process. | |
229 | @end deftypefun | |
230 | ||
231 | @comment unistd.h | |
232 | @comment POSIX.1 | |
233 | @deftypefun int getgroups (int @var{count}, gid_t *@var{groups}) | |
234 | The @code{getgroups} function is used to inquire about the supplementary | |
235 | group IDs of the process. Up to @var{count} of these group IDs are | |
236 | stored in the array @var{groups}; the return value from the function is | |
237 | the number of group IDs actually stored. If @var{count} is smaller than | |
238 | the total number of supplementary group IDs, then @code{getgroups} | |
239 | returns a value of @code{-1} and @code{errno} is set to @code{EINVAL}. | |
240 | ||
241 | If @var{count} is zero, then @code{getgroups} just returns the total | |
242 | number of supplementary group IDs. On systems that do not support | |
243 | supplementary groups, this will always be zero. | |
244 | ||
245 | Here's how to use @code{getgroups} to read all the supplementary group | |
246 | IDs: | |
247 | ||
248 | @smallexample | |
249 | @group | |
250 | gid_t * | |
251 | read_all_groups (void) | |
252 | @{ | |
85f40840 | 253 | int ngroups = getgroups (0, NULL); |
28f540f4 RM |
254 | gid_t *groups |
255 | = (gid_t *) xmalloc (ngroups * sizeof (gid_t)); | |
256 | int val = getgroups (ngroups, groups); | |
257 | if (val < 0) | |
258 | @{ | |
259 | free (groups); | |
260 | return NULL; | |
261 | @} | |
262 | return groups; | |
263 | @} | |
264 | @end group | |
265 | @end smallexample | |
266 | @end deftypefun | |
267 | ||
0413b54c | 268 | @node Setting User ID |
28f540f4 RM |
269 | @section Setting the User ID |
270 | ||
271 | This section describes the functions for altering the user ID (real | |
272 | and/or effective) of a process. To use these facilities, you must | |
273 | include the header files @file{sys/types.h} and @file{unistd.h}. | |
274 | @pindex unistd.h | |
275 | @pindex sys/types.h | |
276 | ||
277 | @comment unistd.h | |
278 | @comment POSIX.1 | |
279 | @deftypefun int setuid (uid_t @var{newuid}) | |
280 | This function sets both the real and effective user ID of the process | |
281 | to @var{newuid}, provided that the process has appropriate privileges. | |
282 | @c !!! also sets saved-id | |
283 | ||
284 | If the process is not privileged, then @var{newuid} must either be equal | |
285 | to the real user ID or the saved user ID (if the system supports the | |
286 | @code{_POSIX_SAVED_IDS} feature). In this case, @code{setuid} sets only | |
287 | the effective user ID and not the real user ID. | |
288 | @c !!! xref to discussion of _POSIX_SAVED_IDS | |
289 | ||
290 | The @code{setuid} function returns a value of @code{0} to indicate | |
291 | successful completion, and a value of @code{-1} to indicate an error. | |
292 | The following @code{errno} error conditions are defined for this | |
293 | function: | |
294 | ||
295 | @table @code | |
296 | @item EINVAL | |
297 | The value of the @var{newuid} argument is invalid. | |
298 | ||
299 | @item EPERM | |
300 | The process does not have the appropriate privileges; you do not | |
301 | have permission to change to the specified ID. | |
302 | @end table | |
303 | @end deftypefun | |
304 | ||
305 | @comment unistd.h | |
306 | @comment BSD | |
307 | @deftypefun int setreuid (uid_t @var{ruid}, uid_t @var{euid}) | |
308 | This function sets the real user ID of the process to @var{ruid} and the | |
309 | effective user ID to @var{euid}. If @var{ruid} is @code{-1}, it means | |
310 | not to change the real user ID; likewise if @var{euid} is @code{-1}, it | |
311 | means not to change the effective user ID. | |
312 | ||
313 | The @code{setreuid} function exists for compatibility with 4.3 BSD Unix, | |
314 | which does not support saved IDs. You can use this function to swap the | |
315 | effective and real user IDs of the process. (Privileged processes are | |
316 | not limited to this particular usage.) If saved IDs are supported, you | |
317 | should use that feature instead of this function. @xref{Enable/Disable | |
318 | Setuid}. | |
319 | ||
320 | The return value is @code{0} on success and @code{-1} on failure. | |
321 | The following @code{errno} error conditions are defined for this | |
322 | function: | |
323 | ||
324 | @table @code | |
325 | @item EPERM | |
326 | The process does not have the appropriate privileges; you do not | |
327 | have permission to change to the specified ID. | |
328 | @end table | |
329 | @end deftypefun | |
330 | ||
0413b54c | 331 | @node Setting Groups |
28f540f4 RM |
332 | @section Setting the Group IDs |
333 | ||
334 | This section describes the functions for altering the group IDs (real | |
335 | and effective) of a process. To use these facilities, you must include | |
336 | the header files @file{sys/types.h} and @file{unistd.h}. | |
337 | @pindex unistd.h | |
338 | @pindex sys/types.h | |
339 | ||
340 | @comment unistd.h | |
341 | @comment POSIX.1 | |
342 | @deftypefun int setgid (gid_t @var{newgid}) | |
343 | This function sets both the real and effective group ID of the process | |
344 | to @var{newgid}, provided that the process has appropriate privileges. | |
345 | @c !!! also sets saved-id | |
346 | ||
347 | If the process is not privileged, then @var{newgid} must either be equal | |
348 | to the real group ID or the saved group ID. In this case, @code{setgid} | |
349 | sets only the effective group ID and not the real group ID. | |
350 | ||
351 | The return values and error conditions for @code{setgid} are the same | |
352 | as those for @code{setuid}. | |
353 | @end deftypefun | |
354 | ||
355 | @comment unistd.h | |
356 | @comment BSD | |
357 | @deftypefun int setregid (gid_t @var{rgid}, fid_t @var{egid}) | |
358 | This function sets the real group ID of the process to @var{rgid} and | |
359 | the effective group ID to @var{egid}. If @var{rgid} is @code{-1}, it | |
360 | means not to change the real group ID; likewise if @var{egid} is | |
361 | @code{-1}, it means not to change the effective group ID. | |
362 | ||
363 | The @code{setregid} function is provided for compatibility with 4.3 BSD | |
364 | Unix, which does not support saved IDs. You can use this function to | |
365 | swap the effective and real group IDs of the process. (Privileged | |
366 | processes are not limited to this usage.) If saved IDs are supported, | |
367 | you should use that feature instead of using this function. | |
368 | @xref{Enable/Disable Setuid}. | |
369 | ||
370 | The return values and error conditions for @code{setregid} are the same | |
371 | as those for @code{setreuid}. | |
372 | @end deftypefun | |
373 | ||
706074a5 | 374 | The GNU system also lets privileged processes change their supplementary |
28f540f4 RM |
375 | group IDs. To use @code{setgroups} or @code{initgroups}, your programs |
376 | should include the header file @file{grp.h}. | |
377 | @pindex grp.h | |
378 | ||
379 | @comment grp.h | |
380 | @comment BSD | |
381 | @deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups}) | |
382 | This function sets the process's supplementary group IDs. It can only | |
383 | be called from privileged processes. The @var{count} argument specifies | |
384 | the number of group IDs in the array @var{groups}. | |
385 | ||
386 | This function returns @code{0} if successful and @code{-1} on error. | |
387 | The following @code{errno} error conditions are defined for this | |
388 | function: | |
389 | ||
390 | @table @code | |
391 | @item EPERM | |
392 | The calling process is not privileged. | |
393 | @end table | |
394 | @end deftypefun | |
395 | ||
396 | @comment grp.h | |
397 | @comment BSD | |
398 | @deftypefun int initgroups (const char *@var{user}, gid_t @var{gid}) | |
399 | The @code{initgroups} function effectively calls @code{setgroups} to | |
400 | set the process's supplementary group IDs to be the normal default for | |
401 | the user name @var{user}. The group ID @var{gid} is also included. | |
402 | @c !!! explain that this works by reading the group file looking for | |
403 | @c groups USER is a member of. | |
404 | @end deftypefun | |
405 | ||
0413b54c | 406 | @node Enable/Disable Setuid |
28f540f4 RM |
407 | @section Enabling and Disabling Setuid Access |
408 | ||
409 | A typical setuid program does not need its special access all of the | |
410 | time. It's a good idea to turn off this access when it isn't needed, | |
411 | so it can't possibly give unintended access. | |
412 | ||
413 | If the system supports the saved user ID feature, you can accomplish | |
414 | this with @code{setuid}. When the game program starts, its real user ID | |
415 | is @code{jdoe}, its effective user ID is @code{games}, and its saved | |
416 | user ID is also @code{games}. The program should record both user ID | |
417 | values once at the beginning, like this: | |
418 | ||
419 | @smallexample | |
420 | user_user_id = getuid (); | |
421 | game_user_id = geteuid (); | |
422 | @end smallexample | |
423 | ||
706074a5 | 424 | Then it can turn off game file access with |
28f540f4 RM |
425 | |
426 | @smallexample | |
427 | setuid (user_user_id); | |
428 | @end smallexample | |
429 | ||
430 | @noindent | |
706074a5 | 431 | and turn it on with |
28f540f4 RM |
432 | |
433 | @smallexample | |
434 | setuid (game_user_id); | |
435 | @end smallexample | |
436 | ||
437 | @noindent | |
438 | Throughout this process, the real user ID remains @code{jdoe} and the | |
439 | saved user ID remains @code{games}, so the program can always set its | |
440 | effective user ID to either one. | |
441 | ||
442 | On other systems that don't support the saved user ID feature, you can | |
443 | turn setuid access on and off by using @code{setreuid} to swap the real | |
444 | and effective user IDs of the process, as follows: | |
445 | ||
446 | @smallexample | |
447 | setreuid (geteuid (), getuid ()); | |
448 | @end smallexample | |
449 | ||
450 | @noindent | |
451 | This special case is always allowed---it cannot fail. | |
452 | ||
453 | Why does this have the effect of toggling the setuid access? Suppose a | |
454 | game program has just started, and its real user ID is @code{jdoe} while | |
455 | its effective user ID is @code{games}. In this state, the game can | |
456 | write the scores file. If it swaps the two uids, the real becomes | |
457 | @code{games} and the effective becomes @code{jdoe}; now the program has | |
458 | only @code{jdoe} access. Another swap brings @code{games} back to | |
459 | the effective user ID and restores access to the scores file. | |
460 | ||
461 | In order to handle both kinds of systems, test for the saved user ID | |
462 | feature with a preprocessor conditional, like this: | |
463 | ||
464 | @smallexample | |
465 | #ifdef _POSIX_SAVED_IDS | |
466 | setuid (user_user_id); | |
467 | #else | |
468 | setreuid (geteuid (), getuid ()); | |
469 | #endif | |
470 | @end smallexample | |
471 | ||
0413b54c | 472 | @node Setuid Program Example |
28f540f4 RM |
473 | @section Setuid Program Example |
474 | ||
475 | Here's an example showing how to set up a program that changes its | |
476 | effective user ID. | |
477 | ||
478 | This is part of a game program called @code{caber-toss} that | |
479 | manipulates a file @file{scores} that should be writable only by the game | |
480 | program itself. The program assumes that its executable | |
481 | file will be installed with the set-user-ID bit set and owned by the | |
482 | same user as the @file{scores} file. Typically, a system | |
483 | administrator will set up an account like @code{games} for this purpose. | |
484 | ||
706074a5 | 485 | The executable file is given mode @code{4755}, so that doing an |
28f540f4 RM |
486 | @samp{ls -l} on it produces output like: |
487 | ||
488 | @smallexample | |
489 | -rwsr-xr-x 1 games 184422 Jul 30 15:17 caber-toss | |
490 | @end smallexample | |
491 | ||
492 | @noindent | |
493 | The set-user-ID bit shows up in the file modes as the @samp{s}. | |
494 | ||
495 | The scores file is given mode @code{644}, and doing an @samp{ls -l} on | |
496 | it shows: | |
497 | ||
498 | @smallexample | |
499 | -rw-r--r-- 1 games 0 Jul 31 15:33 scores | |
500 | @end smallexample | |
501 | ||
502 | Here are the parts of the program that show how to set up the changed | |
503 | user ID. This program is conditionalized so that it makes use of the | |
504 | saved IDs feature if it is supported, and otherwise uses @code{setreuid} | |
505 | to swap the effective and real user IDs. | |
506 | ||
507 | @smallexample | |
508 | #include <stdio.h> | |
509 | #include <sys/types.h> | |
510 | #include <unistd.h> | |
511 | #include <stdlib.h> | |
512 | ||
513 | ||
514 | /* @r{Save the effective and real UIDs.} */ | |
515 | ||
516 | static uid_t euid, ruid; | |
517 | ||
518 | ||
519 | /* @r{Restore the effective UID to its original value.} */ | |
520 | ||
521 | void | |
522 | do_setuid (void) | |
523 | @{ | |
524 | int status; | |
525 | ||
526 | #ifdef _POSIX_SAVED_IDS | |
527 | status = setuid (euid); | |
528 | #else | |
529 | status = setreuid (ruid, euid); | |
530 | #endif | |
531 | if (status < 0) @{ | |
532 | fprintf (stderr, "Couldn't set uid.\n"); | |
533 | exit (status); | |
534 | @} | |
535 | @} | |
536 | ||
537 | ||
538 | @group | |
539 | /* @r{Set the effective UID to the real UID.} */ | |
540 | ||
541 | void | |
542 | undo_setuid (void) | |
543 | @{ | |
544 | int status; | |
545 | ||
546 | #ifdef _POSIX_SAVED_IDS | |
547 | status = setuid (ruid); | |
548 | #else | |
549 | status = setreuid (euid, ruid); | |
550 | #endif | |
551 | if (status < 0) @{ | |
552 | fprintf (stderr, "Couldn't set uid.\n"); | |
553 | exit (status); | |
554 | @} | |
555 | @} | |
556 | @end group | |
557 | ||
558 | /* @r{Main program.} */ | |
559 | ||
560 | int | |
561 | main (void) | |
562 | @{ | |
563 | /* @r{Save the real and effective user IDs.} */ | |
564 | ruid = getuid (); | |
565 | euid = geteuid (); | |
566 | undo_setuid (); | |
567 | ||
568 | /* @r{Do the game and record the score.} */ | |
569 | @dots{} | |
570 | @} | |
571 | @end smallexample | |
572 | ||
573 | Notice how the first thing the @code{main} function does is to set the | |
574 | effective user ID back to the real user ID. This is so that any other | |
575 | file accesses that are performed while the user is playing the game use | |
576 | the real user ID for determining permissions. Only when the program | |
577 | needs to open the scores file does it switch back to the original | |
578 | effective user ID, like this: | |
579 | ||
580 | @smallexample | |
581 | /* @r{Record the score.} */ | |
582 | ||
583 | int | |
584 | record_score (int score) | |
585 | @{ | |
586 | FILE *stream; | |
587 | char *myname; | |
588 | ||
589 | /* @r{Open the scores file.} */ | |
590 | do_setuid (); | |
591 | stream = fopen (SCORES_FILE, "a"); | |
592 | undo_setuid (); | |
593 | ||
594 | @group | |
595 | /* @r{Write the score to the file.} */ | |
596 | if (stream) | |
597 | @{ | |
598 | myname = cuserid (NULL); | |
599 | if (score < 0) | |
600 | fprintf (stream, "%10s: Couldn't lift the caber.\n", myname); | |
601 | else | |
602 | fprintf (stream, "%10s: %d feet.\n", myname, score); | |
603 | fclose (stream); | |
604 | return 0; | |
605 | @} | |
606 | else | |
607 | return -1; | |
608 | @} | |
609 | @end group | |
610 | @end smallexample | |
611 | ||
0413b54c | 612 | @node Tips for Setuid |
28f540f4 RM |
613 | @section Tips for Writing Setuid Programs |
614 | ||
706074a5 | 615 | It is easy for setuid programs to give the user access that isn't |
28f540f4 RM |
616 | intended---in fact, if you want to avoid this, you need to be careful. |
617 | Here are some guidelines for preventing unintended access and | |
618 | minimizing its consequences when it does occur: | |
619 | ||
620 | @itemize @bullet | |
621 | @item | |
622 | Don't have @code{setuid} programs with privileged user IDs such as | |
623 | @code{root} unless it is absolutely necessary. If the resource is | |
624 | specific to your particular program, it's better to define a new, | |
625 | nonprivileged user ID or group ID just to manage that resource. | |
626 | ||
627 | @item | |
628 | Be cautious about using the @code{system} and @code{exec} functions in | |
629 | combination with changing the effective user ID. Don't let users of | |
630 | your program execute arbitrary programs under a changed user ID. | |
631 | Executing a shell is especially bad news. Less obviously, the | |
632 | @code{execlp} and @code{execvp} functions are a potential risk (since | |
633 | the program they execute depends on the user's @code{PATH} environment | |
634 | variable). | |
635 | ||
636 | If you must @code{exec} another program under a changed ID, specify an | |
637 | absolute file name (@pxref{File Name Resolution}) for the executable, | |
638 | and make sure that the protections on that executable and @emph{all} | |
639 | containing directories are such that ordinary users cannot replace it | |
640 | with some other program. | |
641 | ||
642 | @item | |
643 | Only use the user ID controlling the resource in the part of the program | |
644 | that actually uses that resource. When you're finished with it, restore | |
645 | the effective user ID back to the actual user's user ID. | |
646 | @xref{Enable/Disable Setuid}. | |
647 | ||
648 | @item | |
649 | If the @code{setuid} part of your program needs to access other files | |
650 | besides the controlled resource, it should verify that the real user | |
651 | would ordinarily have permission to access those files. You can use the | |
652 | @code{access} function (@pxref{Access Permission}) to check this; it | |
653 | uses the real user and group IDs, rather than the effective IDs. | |
654 | @end itemize | |
655 | ||
0413b54c | 656 | @node Who Logged In |
28f540f4 RM |
657 | @section Identifying Who Logged In |
658 | @cindex login name, determining | |
659 | @cindex user ID, determining | |
660 | ||
661 | You can use the functions listed in this section to determine the login | |
662 | name of the user who is running a process, and the name of the user who | |
663 | logged in the current session. See also the function @code{getuid} and | |
0413b54c UD |
664 | friends (@pxref{Reading Persona}). How this information is collected by |
665 | the system and how to control/add/remove information from the background | |
666 | storage is described in @ref{User Accounting Database}. | |
28f540f4 RM |
667 | |
668 | The @code{getlogin} function is declared in @file{unistd.h}, while | |
669 | @code{cuserid} and @code{L_cuserid} are declared in @file{stdio.h}. | |
670 | @pindex stdio.h | |
671 | @pindex unistd.h | |
672 | ||
673 | @comment unistd.h | |
674 | @comment POSIX.1 | |
675 | @deftypefun {char *} getlogin (void) | |
676 | The @code{getlogin} function returns a pointer to a string containing the | |
677 | name of the user logged in on the controlling terminal of the process, | |
678 | or a null pointer if this information cannot be determined. The string | |
679 | is statically allocated and might be overwritten on subsequent calls to | |
680 | this function or to @code{cuserid}. | |
681 | @end deftypefun | |
682 | ||
683 | @comment stdio.h | |
684 | @comment POSIX.1 | |
685 | @deftypefun {char *} cuserid (char *@var{string}) | |
686 | The @code{cuserid} function returns a pointer to a string containing a | |
687 | user name associated with the effective ID of the process. If | |
688 | @var{string} is not a null pointer, it should be an array that can hold | |
689 | at least @code{L_cuserid} characters; the string is returned in this | |
690 | array. Otherwise, a pointer to a string in a static area is returned. | |
691 | This string is statically allocated and might be overwritten on | |
692 | subsequent calls to this function or to @code{getlogin}. | |
2c6fe0bd UD |
693 | |
694 | The use of this function is deprecated since it is marked to be | |
695 | withdrawn in XPG4.2 and it is already removed in POSIX.1. | |
28f540f4 RM |
696 | @end deftypefun |
697 | ||
698 | @comment stdio.h | |
699 | @comment POSIX.1 | |
700 | @deftypevr Macro int L_cuserid | |
701 | An integer constant that indicates how long an array you might need to | |
702 | store a user name. | |
703 | @end deftypevr | |
704 | ||
705 | These functions let your program identify positively the user who is | |
706 | running or the user who logged in this session. (These can differ when | |
707 | setuid programs are involved; @xref{Process Persona}.) The user cannot | |
708 | do anything to fool these functions. | |
709 | ||
710 | For most purposes, it is more useful to use the environment variable | |
711 | @code{LOGNAME} to find out who the user is. This is more flexible | |
712 | precisely because the user can set @code{LOGNAME} arbitrarily. | |
713 | @xref{Standard Environment}. | |
714 | ||
0413b54c UD |
715 | |
716 | @node User Accounting Database | |
717 | @section The User Accounting Database | |
718 | @cindex user accounting database | |
719 | ||
720 | Most Unix-like operating systems keep track of logged in users by | |
721 | maintaining a user accounting database. This user accounting database | |
722 | stores for each terminal, who has logged on, at what time, the process | |
723 | ID of the user's login shell, etc., etc., but also stores information | |
724 | about the run level of the system, the time of the last system reboot, | |
725 | and possibly more. | |
726 | ||
727 | The user accounting database typically lives in @file{/etc/utmp}, | |
728 | @file{/var/adm/utmp} or @file{/var/run/utmp}. However, these files | |
729 | should @strong{never} be accessed directly. For reading information | |
730 | from and writing information to the user accounting database, the | |
731 | functions described in this section should be used. | |
732 | ||
733 | ||
734 | @menu | |
735 | * Manipulating the Database:: Scanning and modifying the user | |
736 | accounting database. | |
737 | * XPG Functions:: A standardized way for doing the same thing. | |
738 | * Logging In and Out:: Functions from BSD that modify the user | |
739 | accounting database. | |
740 | @end menu | |
741 | ||
742 | @node Manipulating the Database | |
743 | @subsection Manipulating the User Accounting Database | |
744 | ||
745 | These functions and the corresponding data structures are declared in | |
746 | the header file @file{utmp.h}. | |
747 | @pindex utmp.h | |
748 | ||
749 | @comment utmp.h | |
750 | @comment SVID | |
751 | @deftp {Data Type} {struct exit_status} | |
752 | The @code{exit_status} data structure is used to hold information about | |
753 | the exit status of processes marked as @code{DEAD_PROCESS} in the user | |
754 | accounting database. | |
755 | ||
756 | @table @code | |
757 | @item short int e_termination | |
758 | The exit status of the process. | |
759 | ||
760 | @item short int e_exit | |
761 | The exit status of the process. | |
762 | @end table | |
763 | @end deftp | |
764 | ||
765 | @deftp {Data Type} {struct utmp} | |
766 | The @code{utmp} data structure is used to hold information about entries | |
767 | in the user accounting database. On the GNU system it has the following | |
768 | members: | |
769 | ||
770 | @table @code | |
771 | @item short int ut_type | |
772 | Specifies the type of login; one of @code{EMPTY}, @code{RUN_LVL}, | |
773 | @code{BOOT_TIME}, @code{OLD_TIME}, @code{NEW_TIME}, @code{INIT_PROCESS}, | |
774 | @code{LOGIN_PROCESS}, @code{USER_PROCESS}, @code{DEAD_PROCESS} or | |
775 | @code{ACCOUNTING}. | |
776 | ||
777 | @item pid_t ut_pid | |
778 | The process ID number of the login process. | |
779 | ||
780 | @item char ut_line[] | |
781 | The device name of the tty (without @file{/dev/}). | |
782 | ||
783 | @item char ut_id[] | |
784 | The inittab ID of the process. | |
785 | ||
786 | @item char ut_user[] | |
787 | The user's login name. | |
788 | ||
789 | @item char ut_host[] | |
790 | The name of the host from which the user logged in. | |
791 | ||
792 | @item struct exit_status ut_exit | |
793 | The exit status of a process marked as @code{DEAD_PROCESS}. | |
794 | ||
795 | @item long ut_session | |
796 | The Session ID, used for windowing. | |
797 | ||
798 | @item struct timeval ut_tv | |
799 | Time the entry was made. For entries of type @code{OLD_TIME} this is | |
800 | the time when the system clock changed, and for entries of type | |
801 | @code{NEW_TIME} this is the time the system clock was set to. | |
802 | ||
803 | @item int32_t ut_addr_v6[4] | |
804 | The Internet address of a remote host. | |
805 | @end table | |
806 | @end deftp | |
807 | ||
808 | The @code{ut_type}, @code{ut_pid}, @code{ut_id}, @code{ut_tv}, and | |
809 | @code{ut_host} fields are not available on all systems. Portable | |
810 | applications therefore should be prepared for these situations. To help | |
811 | doing this the @file{utmp.h} header provides macros | |
812 | @code{_HAVE_UT_TYPE}, @code{_HAVE_UT_PID}, @code{_HAVE_UT_ID}, | |
813 | @code{_HAVE_UT_TV}, and @code{_HAVE_UT_HOST} if the respective field is | |
814 | available. The programmer can handle the situations by using | |
815 | @code{#ifdef} in the program code. | |
816 | ||
817 | The following macros are defined for use as values for the | |
818 | @code{ut_type} member of the @code{utmp} structure. The values are | |
819 | integer constants. | |
820 | ||
821 | @table @code | |
822 | @comment utmp.h | |
823 | @comment SVID | |
824 | @vindex EMPTY | |
825 | @item EMPTY | |
826 | This macro is used to indicate that the entry contains no valid user | |
827 | accounting information. | |
828 | ||
829 | @comment utmp.h | |
830 | @comment SVID | |
831 | @vindex RUN_LVL | |
832 | @item RUN_LVL | |
833 | This macro is used to identify the systems runlevel. | |
834 | ||
835 | @comment utmp.h | |
836 | @comment SVID | |
837 | @vindex BOOT_TIME | |
838 | @item BOOT_TIME | |
839 | This macro is used to identify the time of system boot. | |
840 | ||
841 | @comment utmp.h | |
842 | @comment SVID | |
843 | @vindex OLD_TIME | |
844 | @item OLD_TIME | |
845 | This macro is used to identify the time when the system clock changed. | |
846 | ||
847 | @comment utmp.h | |
848 | @comment SVID | |
849 | @vindex NEW_TIME | |
850 | @item NEW_TIME | |
851 | This macro is used to identify the time after the system changed. | |
852 | ||
853 | @comment utmp.h | |
854 | @comment SVID | |
855 | @vindex INIT_PROCESS | |
856 | @item INIT_PROCESS | |
857 | This macro is used to identify a process spawned by the init process. | |
858 | ||
859 | @comment utmp.h | |
860 | @comment SVID | |
861 | @vindex LOGIN_PROCESS | |
862 | @item LOGIN_PROCESS | |
863 | This macro is used to identify the session leader of a logged in user. | |
864 | ||
865 | @comment utmp.h | |
866 | @comment SVID | |
867 | @vindex USER_PROCESS | |
868 | @item USER_PROCESS | |
869 | This macro is used to identify a user process. | |
870 | ||
871 | @comment utmp.h | |
872 | @comment SVID | |
873 | @vindex DEAD_PROCESS | |
874 | @item DEAD_PROCESS | |
875 | This macro is used to identify a terminated process. | |
876 | ||
877 | @comment utmp.h | |
878 | @comment SVID | |
879 | @vindex ACCOUNTING | |
880 | @item ACCOUNTING | |
881 | ??? | |
882 | @end table | |
883 | ||
884 | The size of the @code{ut_line}, @code{ut_id}, @code{ut_user} and | |
885 | @code{ut_host} arrays can be found using the @code{sizeof} operator. | |
886 | ||
887 | Many older systems have, instead of an @code{ut_tv} member, an | |
888 | @code{ut_time} member, usually of type @code{time_t}, for representing | |
889 | the time associated with the entry. Therefore, for backwards | |
890 | compatibility only, @file{utmp.h} defines @code{ut_time} as an alias for | |
891 | @code{ut_tv.tv_sec}. | |
892 | ||
893 | @comment utmp.h | |
894 | @comment SVID | |
895 | @deftypefun void setutent (void) | |
896 | This function opens the user accounting database to begin scanning it. | |
897 | You can then call @code{getutent}, @code{getutid} or @code{getutline} to | |
898 | read entries and @code{pututline} to write entries. | |
899 | ||
900 | If the database is already open, it resets the input to the beginning of | |
901 | the database. | |
902 | @end deftypefun | |
903 | ||
904 | @comment utmp.h | |
905 | @comment SVID | |
906 | @deftypefun {struct utmp *} getutent (void) | |
907 | The @code{getutent} function reads the next entry from the user | |
908 | accounting database. It returns a pointer to the entry, which is | |
909 | statically allocated and may be overwritten by subsequent calls to | |
910 | @code{getutent}. You must copy the contents of the structure if you | |
911 | wish to save the information or you can use the @code{getutent_r} | |
912 | function which stores the data in a user-provided buffer. | |
913 | ||
914 | A null pointer is returned in case no further entry is available. | |
915 | @end deftypefun | |
916 | ||
917 | @comment utmp.h | |
918 | @comment SVID | |
919 | @deftypefun void endutent (void) | |
920 | This function closes the user accounting database. | |
921 | @end deftypefun | |
922 | ||
923 | @comment utmp.h | |
924 | @comment SVID | |
925 | @deftypefun {struct utmp *} getutid (const struct utmp *@var{id}) | |
926 | This function searches forward from the current point in the database | |
927 | for an entry that matches @var{id}. If the @code{ut_type} member of the | |
928 | @var{id} structure is one of @code{RUN_LVL}, @code{BOOT_TIME}, | |
929 | @code{OLD_TIME} or @code{NEW_TIME} the entries match if the | |
930 | @code{ut_type} members are identical. If the @code{ut_type} member of | |
931 | the @var{id} structure is @code{INIT_PROCESS}, @code{LOGIN_PROCESS}, | |
932 | @code{USER_PROCESS} or @code{DEAD_PROCESS}, the entries match if the the | |
933 | @code{ut_type} member of the entry read from the database is one of | |
934 | these four, and the @code{ut_id} members match. However if the | |
935 | @code{ut_id} member of either the @var{id} structure or the entry read | |
936 | from the database is empty it checks if the @code{ut_line} members match | |
937 | instead. If a matching entry is found, @code{getutid} returns a pointer | |
938 | to the entry, which is statically allocated, and may be overwritten by a | |
939 | subsequent call to @code{getutent}, @code{getutid} or @code{getutline}. | |
940 | You must copy the contents of the structure if you wish to save the | |
941 | information. | |
942 | ||
943 | A null pointer is returned in case the end of the database is reached | |
944 | without a match. | |
945 | ||
946 | The @code{getutid} function may cache the last read entry. Therefore, | |
947 | if you are using @code{getutid} to search for multiple occurrences, it | |
948 | is necessary to zero out the static data after each call. Otherwise | |
949 | @code{getutid} could just return a pointer to the same entry over and | |
950 | over again. | |
951 | @end deftypefun | |
952 | ||
953 | @comment utmp.h | |
954 | @comment SVID | |
955 | @deftypefun {struct utmp *} getutline (const struct utmp *@var{line}) | |
956 | This function searches forward from the current point in the database | |
957 | until it finds an entry whose @code{ut_type} value is | |
958 | @code{LOGIN_PROCESS} or @code{USER_PROCESS}, and whose @code{ut_line} | |
959 | member matches the @code{ut_line} member of the @var{line} structure. | |
960 | If it finds such an entry, it returns a pointer to the entry which is | |
961 | statically allocated, and may be overwritten by a subsequent call to | |
962 | @code{getutent}, @code{getutid} or @code{getutline}. You must copy the | |
963 | contents of the structure if you wish to save the information. | |
964 | ||
965 | A null pointer is returned in case the end of the database is reached | |
966 | without a match. | |
967 | ||
968 | The @code{getutline} function may cache the last read entry. Therefore | |
969 | if you are using @code{getutline} to search for multiple occurrences, it | |
970 | is necessary to zero out the static data after each call. Otherwise | |
971 | @code{getutline} could just return a pointer to the same entry over and | |
972 | over again. | |
973 | @end deftypefun | |
974 | ||
975 | @comment utmp.h | |
976 | @comment SVID | |
977 | @deftypefun {struct utmp *} pututline (const struct utmp *@var{utmp}) | |
978 | The @code{pututline} function inserts the entry @code{*@var{utmp}} at | |
979 | the appropriate place in the user accounting database. If it finds that | |
980 | it is not already at the correct place in the database, it uses | |
981 | @code{getutid} to search for the position to insert the entry, however | |
982 | this will not modify the static structure returned by @code{getutent}, | |
983 | @code{getutid} and @code{getutline}. If this search fails, the entry | |
984 | is appended to the database. | |
985 | ||
986 | The @code{pututline} function returns a pointer to a copy of the entry | |
987 | inserted in the user accounting database, or a null pointer if the entry | |
988 | could not be added. The following @code{errno} error conditions are | |
989 | defined for this function: | |
990 | ||
991 | @table @code | |
992 | @item EPERM | |
993 | The process does not have the appropriate privileges; you cannot modify | |
994 | the user accounting database. | |
995 | @end table | |
996 | @end deftypefun | |
997 | ||
998 | All the @code{get*} functions mentioned before store the information | |
999 | they return in a static buffer. This can be a problem in multi-threaded | |
1000 | programs since the data return for the request is overwritten be the | |
1001 | return value data in another thread. Therefore the GNU C Library | |
1002 | provides as extensions three more functions which return the data in a | |
1003 | user-provided buffer. | |
1004 | ||
1005 | @comment utmp.h | |
1006 | @comment GNU | |
1007 | @deftypefun int getutent_r (struct utmp *@var{buffer}, struct utmp **@var{result}) | |
1008 | The @code{getutent_r} is equivalent to the @code{getutent} function. It | |
1009 | returns the next entry from the database. But instead of storing the | |
1010 | information in a static buffer it stores it in the buffer pointed to by | |
1011 | the parameter @var{buffer}. | |
1012 | ||
1013 | If the call was successful, the function returns @code{0} and the | |
1014 | pointer variable pointed to by the parameter @var{result} contains a | |
1015 | pointer to the buffer which contains the result (this is most probably | |
1016 | the same value as @var{buffer}). If something went wrong during the | |
1017 | execution of @code{getutent_r} the function returns @code{-1}. | |
1018 | ||
1019 | This function is a GNU extension. | |
1020 | @end deftypefun | |
1021 | ||
1022 | @comment utmp.h | |
1023 | @comment GNU | |
1024 | @deftypefun int getutid_r (const struct utmp *@var{id}, struct utmp *@var{buffer}, struct utmp **@var{result}) | |
1025 | This function retrieves just like @code{getutid} the next entry matching | |
1026 | the information stored in @var{id}. But the result is stored in the | |
1027 | buffer pointed to by the parameter @var{buffer}. | |
1028 | ||
1029 | If successful the function returns @code{0} and the pointer variable | |
1030 | pointed to by the parameter @var{result} contains a pointer to the | |
1031 | buffer with the result (probably the same as @var{result}. If not | |
1032 | successful the function return @code{-1}. | |
1033 | ||
1034 | This function is a GNU extension. | |
1035 | @end deftypefun | |
1036 | ||
1037 | @comment utmp.h | |
1038 | @comment GNU | |
1039 | @deftypefun int getutline_r (const struct utmp *@var{line}, struct utmp *@var{buffer}, struct utmp **@var{result}) | |
1040 | This function retrieves just like @code{getutline} the next entry | |
1041 | matching the information stored in @var{line}. But the result is stored | |
1042 | in the buffer pointed to by the parameter @var{buffer}. | |
1043 | ||
1044 | If successful the function returns @code{0} and the pointer variable | |
1045 | pointed to by the parameter @var{result} contains a pointer to the | |
1046 | buffer with the result (probably the same as @var{result}. If not | |
1047 | successful the function return @code{-1}. | |
1048 | ||
1049 | This function is a GNU extension. | |
1050 | @end deftypefun | |
1051 | ||
1052 | ||
1053 | In addition to the user accounting database, most systems keep a number | |
1054 | of similar databases. For example most systems keep a log file with all | |
1055 | previous logins (usually in @file{/etc/wtmp} or @file{/var/log/wtmp}). | |
1056 | ||
1057 | For specifying which database to examine, the following function should | |
1058 | be used. | |
1059 | ||
1060 | @comment utmp.h | |
1061 | @comment SVID | |
1062 | @deftypefun int utmpname (const char *@var{file}) | |
1063 | The @code{utmpname} function changes the name of the database to be | |
1064 | examined to @var{file}, and closes any previously opened database. By | |
1065 | default @code{getutent}, @code{getutid}, @code{getutline} and | |
1066 | @code{pututline} read from and write to the user accounting database. | |
1067 | ||
1068 | The following macros are defined for use as the @var{file} argument: | |
1069 | ||
1070 | @deftypevr Macro {char *} _PATH_UTMP | |
1071 | This macro is used to specify the user accounting database. | |
1072 | @end deftypevr | |
1073 | ||
1074 | @deftypevr Macro {char *} _PATH_WTMP | |
1075 | This macro is used to specify the user accounting log file. | |
1076 | @end deftypevr | |
1077 | ||
1078 | The @code{utmpname} function returns a value of @code{0} if the new name | |
1079 | was successfully stored, and a value of @code{-1} to indicate an error. | |
1080 | Note that @code{utmpname} does not try open the database, and that | |
1081 | therefore the return value does not say anything about whether the | |
1082 | database can be successfully opened. | |
1083 | @end deftypefun | |
1084 | ||
1085 | Specially for maintaining log-like databases the GNU C Library provides | |
1086 | the following function: | |
1087 | ||
1088 | @comment utmp.h | |
1089 | @comment SVID | |
1090 | @deftypefun void updwtmp (const char *@var{wtmp_file}, const struct utmp *@var{utmp}) | |
1091 | The @code{updwtmp} function appends the entry *@var{utmp} to the | |
1092 | database specified by @var{wtmp_file}. For possible values for the | |
1093 | @var{wtmp_file} argument see the @code{utmpname} function. | |
1094 | @end deftypefun | |
1095 | ||
1096 | @strong{Portability Note:} Although many operating systems provide a | |
1097 | subset of these functions, they are not standardized. There are often | |
1098 | subtle differences in the return types, and there are considerable | |
1099 | differences between the various definitions of @code{struct utmp}. When | |
1100 | programming for the GNU system, it is probably probably best to stick | |
1101 | with the functions described in this section. If however, you want your | |
1102 | program to be portable, consider using the XPG functions described in | |
1103 | @ref{XPG Functions}, or take a look at the BSD compatible functions in | |
1104 | @ref{Logging In and Out}. | |
1105 | ||
1106 | ||
1107 | @node XPG Functions | |
1108 | @subsection XPG User Accounting Database Functions | |
1109 | ||
1110 | These functions, described in the X/Open Portability Guide, are declared | |
1111 | in the header file @file{utmpx.h}. | |
1112 | @pindex utmpx.h | |
1113 | ||
1114 | @deftp {Data Type} {struct utmpx} | |
1115 | The @code{utmpx} data structure contains at least the following members: | |
1116 | ||
1117 | @table @code | |
1118 | @item short int ut_type | |
1119 | Specifies the type of login; one of @code{EMPTY}, @code{RUN_LVL}, | |
1120 | @code{BOOT_TIME}, @code{OLD_TIME}, @code{NEW_TIME}, @code{INIT_PROCESS}, | |
1121 | @code{LOGIN_PROCESS}, @code{USER_PROCESS} or @code{DEAD_PROCESS}. | |
1122 | ||
1123 | @item pid_t ut_pid | |
1124 | The process ID number of the login process. | |
1125 | ||
1126 | @item char ut_line[] | |
1127 | The device name of the tty (without @file{/dev/}). | |
1128 | ||
1129 | @item char ut_id[] | |
1130 | The inittab ID of the process. | |
1131 | ||
1132 | @item char ut_user[] | |
1133 | The user's login name. | |
1134 | ||
1135 | @item struct timeval ut_tv | |
1136 | Time the entry was made. For entries of type @code{OLD_TIME} this is | |
1137 | the time when the system clock changed, and for entries of type | |
1138 | @code{NEW_TIME} this is the time the system clock was set to. | |
1139 | @end table | |
1140 | On the GNU system, @code{struct utmpx} is identical to @code{struct | |
1141 | utmp} except for the fact that including @file{utmpx.h} does not make | |
1142 | visible the declaration of @code{struct exit_status}. | |
1143 | @end deftp | |
1144 | ||
1145 | The following macros are defined for use as values for the | |
1146 | @code{ut_type} member of the @code{utmpx} structure. The values are | |
1147 | integer constants and are, on the GNU system, identical to the | |
1148 | definitions in @file{utmp.h}. | |
1149 | ||
1150 | @table @code | |
1151 | @comment utmpx.h | |
1152 | @comment XPG4.2 | |
1153 | @vindex EMPTY | |
1154 | @item EMPTY | |
1155 | This macro is used to indicate that the entry contains no valid user | |
1156 | accounting information. | |
1157 | ||
1158 | @comment utmpx.h | |
1159 | @comment XPG4.2 | |
1160 | @vindex RUN_LVL | |
1161 | @item RUN_LVL | |
1162 | This macro is used to identify the systems runlevel. | |
1163 | ||
1164 | @comment utmpx.h | |
1165 | @comment XPG4.2 | |
1166 | @vindex BOOT_TIME | |
1167 | @item BOOT_TIME | |
1168 | This macro is used to identify the time of system boot. | |
1169 | ||
1170 | @comment utmpx.h | |
1171 | @comment XPG4.2 | |
1172 | @vindex OLD_TIME | |
1173 | @item OLD_TIME | |
1174 | This macro is used to identify the time when the system clock changed. | |
1175 | ||
1176 | @comment utmpx.h | |
1177 | @comment XPG4.2 | |
1178 | @vindex NEW_TIME | |
1179 | @item NEW_TIME | |
1180 | This macro is used to identify the time after the system changed. | |
1181 | ||
1182 | @comment utmpx.h | |
1183 | @comment XPG4.2 | |
1184 | @vindex INIT_PROCESS | |
1185 | @item INIT_PROCESS | |
1186 | This macro is used to identify a process spawned by the init process. | |
1187 | ||
1188 | @comment utmpx.h | |
1189 | @comment XPG4.2 | |
1190 | @vindex LOGIN_PROCESS | |
1191 | @item LOGIN_PROCESS | |
1192 | This macro is used to identify the session leader of a logged in user. | |
1193 | ||
1194 | @comment utmpx.h | |
1195 | @comment XPG4.2 | |
1196 | @vindex USER_PROCESS | |
1197 | @item USER_PROCESS | |
1198 | This macro is used to identify a user process. | |
1199 | ||
1200 | @comment utmpx.h | |
1201 | @comment XPG4.2 | |
1202 | @vindex DEAD_PROCESS | |
1203 | @item DEAD_PROCESS | |
1204 | This macro is used to identify a terminated process. | |
1205 | @end table | |
1206 | ||
1207 | The size of the @code{ut_line}, @code{ut_id} and @code{ut_user} arrays | |
1208 | can be found using the @code{sizeof} operator. | |
1209 | ||
1210 | @comment utmpx.h | |
1211 | @comment XPG4.2 | |
1212 | @deftypefun void setutxent (void) | |
1213 | This function is similar to @code{setutent}. On the GNU system it is | |
1214 | simply an alias for @code{setutent}. | |
1215 | @end deftypefun | |
1216 | ||
1217 | @comment utmpx.h | |
1218 | @comment XPG4.2 | |
1219 | @deftypefun {struct utmpx *} getutxent (void) | |
1220 | The @code{getutxent} function is similar to @code{getutent}, but returns | |
1221 | a pointer to a @code{struct utmpx} instead of @code{struct utmp}. On | |
1222 | the GNU system it simply is an alias for @code{getutent}. | |
1223 | @end deftypefun | |
1224 | ||
1225 | @comment utmpx.h | |
1226 | @comment XPG4.2 | |
1227 | @deftypefun void endutxent (void) | |
1228 | This function is similar to @code{endutent}. On the GNU system it is | |
1229 | simply an alias for @code{endutent}. | |
1230 | @end deftypefun | |
1231 | ||
1232 | @comment utmpx.h | |
1233 | @comment XPG4.2 | |
1234 | @deftypefun {struct utmpx *} getutxid (const struct utmpx *@var{id}) | |
1235 | This function is similar to @code{getutid}, but uses @code{struct utmpx} | |
1236 | instead of @code{struct utmp}. On the GNU system it is simply an alias | |
1237 | for @code{getutid}. | |
1238 | @end deftypefun | |
1239 | ||
1240 | @comment utmpx.h | |
1241 | @comment XPG4.2 | |
1242 | @deftypefun {struct utmpx *} getutxline (const struct utmpx *@var{line}) | |
1243 | This function is similar to @code{getutid}, but uses @code{struct utmpx} | |
1244 | instead of @code{struct utmp}. On the GNU system it is simply an alias | |
1245 | for @code{getutline}. | |
1246 | @end deftypefun | |
1247 | ||
1248 | @comment utmpx.h | |
1249 | @comment XPG4.2 | |
1250 | @deftypefun {struct utmpx *} pututxline (const struct utmpx *@var{utmp}) | |
1251 | The @code{pututxline} function provides functionality identical to | |
1252 | @code{pututline}, but uses @code{struct utmpx} instead of @code{struct | |
1253 | utmp}. On the GNU system @code{pututxline} is simply an alias for | |
1254 | @code{pututline}. | |
1255 | @end deftypefun | |
1256 | ||
1257 | ||
1258 | @node Logging In and Out | |
1259 | @subsection Logging In and Out | |
1260 | ||
1261 | These functions, derived from BSD, are available in the separate | |
1262 | @file{libutil} library, and declared in @file{utmp.h}. | |
1263 | @pindex utmp.h | |
1264 | ||
1265 | Note that the @code{ut_user} member of @code{struct utmp} is called | |
1266 | @code{ut_name} in BSD. Therefore, @code{ut_name} is defined as an alias | |
1267 | for @code{ut_user} in @file{utmp.h}. | |
1268 | ||
1269 | @comment utmp.h | |
1270 | @comment BSD | |
1271 | @deftypefun int login_tty (int @var{filedes}) | |
1272 | This function makes @var{filedes} the controlling terminal of the | |
1273 | current process, redirects standard input, standard output and | |
1274 | standard error output to this terminal, and closes @var{filedes}. | |
1275 | ||
1276 | This function returns @code{0} on successful completion, and @code{-1} | |
1277 | on error. | |
1278 | @end deftypefun | |
1279 | ||
1280 | @comment utmp.h | |
1281 | @comment BSD | |
1282 | @deftypefun void login (const struct utmp *@var{entry}) | |
1283 | The @code{login} functions inserts an entry into the user accounting | |
1284 | database. The @code{ut_line} member is set to the name of the terminal | |
1285 | on standard input. If standard input is not a terminal @code{login} | |
1286 | uses standard output or standard error output to determine the name of | |
1287 | the terminal. If @code{struct utmp} has a @code{ut_type} member, | |
1288 | @code{login} sets it to @code{USER_PROCESS}, and if there is an | |
1289 | @code{ut_pid} member, it will be set to the process ID of the current | |
1290 | process. The remaining entries are copied from @var{entry}. | |
1291 | ||
1292 | A copy of the entry is written to the user accounting log file. | |
1293 | @end deftypefun | |
1294 | ||
1295 | @comment utmp.h | |
1296 | @comment BSD | |
1297 | @deftypefun int logout (const char *@var{ut_line}) | |
1298 | This function modifies the user accounting database to indicate that the | |
1299 | user on @var{ut_line} has logged out. | |
1300 | ||
1301 | The @code{logout} function returns @code{1} if the entry was successfully | |
1302 | written to the database, or @code{0} on error. | |
1303 | @end deftypefun | |
1304 | ||
1305 | @comment utmp.h | |
1306 | @comment BSD | |
1307 | @deftypefun void logwtmp (const char *@var{ut_line}, const char *@var{ut_name}, const char *@var{ut_host}) | |
1308 | The @code{logwtmp} function appends an entry to the user accounting log | |
1309 | file, for the current time and the information provided in the | |
1310 | @var{ut_line}, @var{ut_name} and @var{ut_host} arguments. | |
1311 | @end deftypefun | |
1312 | ||
1313 | @strong{Portability Note:} The BSD @code{struct utmp} only has the | |
1314 | @code{ut_line}, @code{ut_name}, @code{ut_host} and @code{ut_time} | |
1315 | members. Older systems do not even have the @code{ut_host} member. | |
1316 | ||
1317 | ||
1318 | @node User Database | |
28f540f4 RM |
1319 | @section User Database |
1320 | @cindex user database | |
1321 | @cindex password database | |
1322 | @pindex /etc/passwd | |
1323 | ||
1324 | This section describes all about how to search and scan the database of | |
1325 | registered users. The database itself is kept in the file | |
1326 | @file{/etc/passwd} on most systems, but on some systems a special | |
1327 | network server gives access to it. | |
1328 | ||
1329 | @menu | |
1330 | * User Data Structure:: What each user record contains. | |
1331 | * Lookup User:: How to look for a particular user. | |
1332 | * Scanning All Users:: Scanning the list of all users, one by one. | |
1333 | * Writing a User Entry:: How a program can rewrite a user's record. | |
1334 | @end menu | |
1335 | ||
0413b54c | 1336 | @node User Data Structure |
28f540f4 RM |
1337 | @subsection The Data Structure that Describes a User |
1338 | ||
1339 | The functions and data structures for accessing the system user database | |
1340 | are declared in the header file @file{pwd.h}. | |
1341 | @pindex pwd.h | |
1342 | ||
1343 | @comment pwd.h | |
1344 | @comment POSIX.1 | |
1345 | @deftp {Data Type} {struct passwd} | |
706074a5 | 1346 | The @code{passwd} data structure is used to hold information about |
28f540f4 RM |
1347 | entries in the system user data base. It has at least the following members: |
1348 | ||
1349 | @table @code | |
1350 | @item char *pw_name | |
1351 | The user's login name. | |
1352 | ||
1353 | @item char *pw_passwd. | |
1354 | The encrypted password string. | |
1355 | ||
1356 | @item uid_t pw_uid | |
1357 | The user ID number. | |
1358 | ||
1359 | @item gid_t pw_gid | |
1360 | The user's default group ID number. | |
1361 | ||
1362 | @item char *pw_gecos | |
1363 | A string typically containing the user's real name, and possibly other | |
1364 | information such as a phone number. | |
1365 | ||
1366 | @item char *pw_dir | |
1367 | The user's home directory, or initial working directory. This might be | |
1368 | a null pointer, in which case the interpretation is system-dependent. | |
1369 | ||
1370 | @item char *pw_shell | |
1371 | The user's default shell, or the initial program run when the user logs in. | |
1372 | This might be a null pointer, indicating that the system default should | |
1373 | be used. | |
1374 | @end table | |
1375 | @end deftp | |
1376 | ||
0413b54c | 1377 | @node Lookup User |
28f540f4 RM |
1378 | @subsection Looking Up One User |
1379 | @cindex converting user ID to user name | |
1380 | @cindex converting user name to user ID | |
1381 | ||
1382 | You can search the system user database for information about a | |
1383 | specific user using @code{getpwuid} or @code{getpwnam}. These | |
1384 | functions are declared in @file{pwd.h}. | |
1385 | ||
1386 | @comment pwd.h | |
1387 | @comment POSIX.1 | |
1388 | @deftypefun {struct passwd *} getpwuid (uid_t @var{uid}) | |
1389 | This function returns a pointer to a statically-allocated structure | |
1390 | containing information about the user whose user ID is @var{uid}. This | |
1391 | structure may be overwritten on subsequent calls to @code{getpwuid}. | |
1392 | ||
1393 | A null pointer value indicates there is no user in the data base with | |
1394 | user ID @var{uid}. | |
1395 | @end deftypefun | |
1396 | ||
ba1ffaa1 UD |
1397 | @comment pwd.h |
1398 | @comment POSIX.1c | |
1399 | @deftypefun int getpwuid_r (uid_t @var{uid}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) | |
1400 | This function is similar to @code{getpwuid} in that is returns | |
1401 | information about the user whose user ID is @var{uid}. But the result | |
1402 | is not placed in a static buffer. Instead the user supplied structure | |
1403 | pointed to by @var{result_buf} is filled with the information. The | |
1404 | first @var{buflen} bytes of the additional buffer pointed to by | |
1405 | @var{buffer} are used to contain additional information, normally | |
1406 | strings which are pointed to by the elements of the result structure. | |
1407 | ||
1408 | If the return value is @code{0} the pointer returned in @var{result} | |
1409 | points to the record which contains the wanted data (i.e., @var{result} | |
1410 | contains the value @var{result_buf}). In case the return value is non | |
1411 | null there is no user in the data base with user ID @var{uid} or the | |
1412 | buffer @var{buffer} is too small to contain all the needed information. | |
1413 | In the later case the global @var{errno} variable is set to | |
1414 | @code{ERANGE}. | |
1415 | @end deftypefun | |
1416 | ||
1417 | ||
28f540f4 RM |
1418 | @comment pwd.h |
1419 | @comment POSIX.1 | |
1420 | @deftypefun {struct passwd *} getpwnam (const char *@var{name}) | |
1421 | This function returns a pointer to a statically-allocated structure | |
1422 | containing information about the user whose user name is @var{name}. | |
1423 | This structure may be overwritten on subsequent calls to | |
1424 | @code{getpwnam}. | |
1425 | ||
1426 | A null pointer value indicates there is no user named @var{name}. | |
1427 | @end deftypefun | |
1428 | ||
ba1ffaa1 UD |
1429 | @comment pwd.h |
1430 | @comment POSIX.1c | |
1431 | @deftypefun int getpwnam_r (const char *@var{name}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) | |
1432 | This function is similar to @code{getpwnam} in that is returns | |
1433 | information about the user whose user name is @var{name}. But the result | |
1434 | is not placed in a static buffer. Instead the user supplied structure | |
1435 | pointed to by @var{result_buf} is filled with the information. The | |
1436 | first @var{buflen} bytes of the additional buffer pointed to by | |
1437 | @var{buffer} are used to contain additional information, normally | |
1438 | strings which are pointed to by the elements of the result structure. | |
1439 | ||
1440 | If the return value is @code{0} the pointer returned in @var{result} | |
1441 | points to the record which contains the wanted data (i.e., @var{result} | |
1442 | contains the value @var{result_buf}). In case the return value is non | |
1443 | null there is no user in the data base with user name @var{name} or the | |
1444 | buffer @var{buffer} is too small to contain all the needed information. | |
1445 | In the later case the global @var{errno} variable is set to | |
1446 | @code{ERANGE}. | |
1447 | @end deftypefun | |
1448 | ||
1449 | ||
0413b54c | 1450 | @node Scanning All Users |
28f540f4 RM |
1451 | @subsection Scanning the List of All Users |
1452 | @cindex scanning the user list | |
1453 | ||
1454 | This section explains how a program can read the list of all users in | |
1455 | the system, one user at a time. The functions described here are | |
1456 | declared in @file{pwd.h}. | |
1457 | ||
1458 | You can use the @code{fgetpwent} function to read user entries from a | |
1459 | particular file. | |
1460 | ||
1461 | @comment pwd.h | |
1462 | @comment SVID | |
1463 | @deftypefun {struct passwd *} fgetpwent (FILE *@var{stream}) | |
1464 | This function reads the next user entry from @var{stream} and returns a | |
1465 | pointer to the entry. The structure is statically allocated and is | |
1466 | rewritten on subsequent calls to @code{fgetpwent}. You must copy the | |
1467 | contents of the structure if you wish to save the information. | |
1468 | ||
1469 | This stream must correspond to a file in the same format as the standard | |
1470 | password database file. This function comes from System V. | |
1471 | @end deftypefun | |
1472 | ||
ba1ffaa1 UD |
1473 | @comment pwd.h |
1474 | @comment GNU | |
1475 | @deftypefun int fgetpwent_r (FILE *@var{stream}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result}) | |
1476 | This function is similar to @code{fgetpwent} in that it reads the next | |
1477 | user entry from @var{stream}. But the result is returned in the | |
1478 | structure pointed to by @var{result_buf}. The | |
1479 | first @var{buflen} bytes of the additional buffer pointed to by | |
1480 | @var{buffer} are used to contain additional information, normally | |
1481 | strings which are pointed to by the elements of the result structure. | |
1482 | ||
1483 | This stream must correspond to a file in the same format as the standard | |
1484 | password database file. | |
1485 | ||
26761c28 | 1486 | If the function returns null @var{result} points to the structure with |
ba1ffaa1 | 1487 | the wanted data (normally this is in @var{result_buf}). If errors |
6d52618b | 1488 | occurred the return value is non-null and @var{result} contains a null |
ba1ffaa1 UD |
1489 | pointer. |
1490 | @end deftypefun | |
1491 | ||
28f540f4 RM |
1492 | The way to scan all the entries in the user database is with |
1493 | @code{setpwent}, @code{getpwent}, and @code{endpwent}. | |
1494 | ||
1495 | @comment pwd.h | |
1496 | @comment SVID, BSD | |
1497 | @deftypefun void setpwent (void) | |
ba1ffaa1 UD |
1498 | This function initializes a stream which @code{getpwent} and |
1499 | @code{getpwent_r} use to read the user database. | |
28f540f4 RM |
1500 | @end deftypefun |
1501 | ||
1502 | @comment pwd.h | |
1503 | @comment POSIX.1 | |
1504 | @deftypefun {struct passwd *} getpwent (void) | |
1505 | The @code{getpwent} function reads the next entry from the stream | |
1506 | initialized by @code{setpwent}. It returns a pointer to the entry. The | |
1507 | structure is statically allocated and is rewritten on subsequent calls | |
1508 | to @code{getpwent}. You must copy the contents of the structure if you | |
1509 | wish to save the information. | |
ba1ffaa1 UD |
1510 | |
1511 | A null pointer is returned in case no further entry is available. | |
1512 | @end deftypefun | |
1513 | ||
1514 | @comment pwd.h | |
1515 | @comment GNU | |
1516 | @deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, int @var{buflen}, struct passwd **@var{result}) | |
1517 | This function is similar to @code{getpwent} in that it returns the next | |
1518 | entry from the stream initialized by @code{setpwent}. But in contrast | |
1519 | to the @code{getpwent} function this function is reentrant since the | |
1520 | result is placed in the user supplied structure pointed to by | |
1521 | @var{result_buf}. Additional data, normally the strings pointed to by | |
1522 | the elements of the result structure, are placed in the additional | |
1523 | buffer or length @var{buflen} starting at @var{buffer}. | |
1524 | ||
26761c28 | 1525 | If the function returns zero @var{result} points to the structure with |
ba1ffaa1 | 1526 | the wanted data (normally this is in @var{result_buf}). If errors |
6d52618b | 1527 | occurred the return value is non-zero and @var{result} contains a null |
ba1ffaa1 | 1528 | pointer. |
28f540f4 RM |
1529 | @end deftypefun |
1530 | ||
1531 | @comment pwd.h | |
1532 | @comment SVID, BSD | |
1533 | @deftypefun void endpwent (void) | |
ba1ffaa1 UD |
1534 | This function closes the internal stream used by @code{getpwent} or |
1535 | @code{getpwent_r}. | |
28f540f4 RM |
1536 | @end deftypefun |
1537 | ||
0413b54c | 1538 | @node Writing a User Entry |
28f540f4 RM |
1539 | @subsection Writing a User Entry |
1540 | ||
1541 | @comment pwd.h | |
1542 | @comment SVID | |
1543 | @deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream}) | |
1544 | This function writes the user entry @code{*@var{p}} to the stream | |
1545 | @var{stream}, in the format used for the standard user database | |
1546 | file. The return value is zero on success and nonzero on failure. | |
1547 | ||
1548 | This function exists for compatibility with SVID. We recommend that you | |
1549 | avoid using it, because it makes sense only on the assumption that the | |
1550 | @code{struct passwd} structure has no members except the standard ones; | |
1551 | on a system which merges the traditional Unix data base with other | |
1552 | extended information about users, adding an entry using this function | |
1553 | would inevitably leave out much of the important information. | |
1554 | ||
1555 | The function @code{putpwent} is declared in @file{pwd.h}. | |
1556 | @end deftypefun | |
1557 | ||
0413b54c | 1558 | @node Group Database |
28f540f4 RM |
1559 | @section Group Database |
1560 | @cindex group database | |
1561 | @pindex /etc/group | |
1562 | ||
1563 | This section describes all about how to search and scan the database of | |
1564 | registered groups. The database itself is kept in the file | |
1565 | @file{/etc/group} on most systems, but on some systems a special network | |
1566 | service provides access to it. | |
1567 | ||
1568 | @menu | |
1569 | * Group Data Structure:: What each group record contains. | |
1570 | * Lookup Group:: How to look for a particular group. | |
1571 | * Scanning All Groups:: Scanning the list of all groups. | |
1572 | @end menu | |
1573 | ||
0413b54c | 1574 | @node Group Data Structure |
28f540f4 RM |
1575 | @subsection The Data Structure for a Group |
1576 | ||
1577 | The functions and data structures for accessing the system group | |
1578 | database are declared in the header file @file{grp.h}. | |
1579 | @pindex grp.h | |
1580 | ||
1581 | @comment grp.h | |
1582 | @comment POSIX.1 | |
706074a5 | 1583 | @deftp {Data Type} {struct group} |
28f540f4 RM |
1584 | The @code{group} structure is used to hold information about an entry in |
1585 | the system group database. It has at least the following members: | |
1586 | ||
1587 | @table @code | |
1588 | @item char *gr_name | |
1589 | The name of the group. | |
1590 | ||
1591 | @item gid_t gr_gid | |
1592 | The group ID of the group. | |
1593 | ||
1594 | @item char **gr_mem | |
1595 | A vector of pointers to the names of users in the group. Each user name | |
1596 | is a null-terminated string, and the vector itself is terminated by a | |
1597 | null pointer. | |
1598 | @end table | |
1599 | @end deftp | |
1600 | ||
0413b54c | 1601 | @node Lookup Group |
28f540f4 RM |
1602 | @subsection Looking Up One Group |
1603 | @cindex converting group name to group ID | |
1604 | @cindex converting group ID to group name | |
1605 | ||
1606 | You can search the group database for information about a specific | |
1607 | group using @code{getgrgid} or @code{getgrnam}. These functions are | |
1608 | declared in @file{grp.h}. | |
1609 | ||
1610 | @comment grp.h | |
1611 | @comment POSIX.1 | |
1612 | @deftypefun {struct group *} getgrgid (gid_t @var{gid}) | |
1613 | This function returns a pointer to a statically-allocated structure | |
1614 | containing information about the group whose group ID is @var{gid}. | |
1615 | This structure may be overwritten by subsequent calls to | |
1616 | @code{getgrgid}. | |
1617 | ||
1618 | A null pointer indicates there is no group with ID @var{gid}. | |
1619 | @end deftypefun | |
1620 | ||
ba1ffaa1 UD |
1621 | @comment grp.h |
1622 | @comment POSIX.1c | |
1623 | @deftypefun int getgrgid_r (gid_t @var{gid}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) | |
1624 | This function is similar to @code{getgrgid} in that is returns | |
1625 | information about the group whose group ID is @var{gid}. But the result | |
1626 | is not placed in a static buffer. Instead the user supplied structure | |
1627 | pointed to by @var{result_buf} is filled with the information. The | |
1628 | first @var{buflen} bytes of the additional buffer pointed to by | |
1629 | @var{buffer} are used to contain additional information, normally | |
1630 | strings which are pointed to by the elements of the result structure. | |
1631 | ||
1632 | If the return value is @code{0} the pointer returned in @var{result} | |
1633 | points to the record which contains the wanted data (i.e., @var{result} | |
26761c28 UD |
1634 | contains the value @var{result_buf}). If the return value is non-zero |
1635 | there is no group in the data base with group ID @var{gid} or the | |
ba1ffaa1 UD |
1636 | buffer @var{buffer} is too small to contain all the needed information. |
1637 | In the later case the global @var{errno} variable is set to | |
1638 | @code{ERANGE}. | |
1639 | @end deftypefun | |
1640 | ||
28f540f4 RM |
1641 | @comment grp.h |
1642 | @comment SVID, BSD | |
1643 | @deftypefun {struct group *} getgrnam (const char *@var{name}) | |
1644 | This function returns a pointer to a statically-allocated structure | |
1645 | containing information about the group whose group name is @var{name}. | |
1646 | This structure may be overwritten by subsequent calls to | |
1647 | @code{getgrnam}. | |
1648 | ||
1649 | A null pointer indicates there is no group named @var{name}. | |
1650 | @end deftypefun | |
1651 | ||
ba1ffaa1 UD |
1652 | @comment grp.h |
1653 | @comment POSIX.1c | |
1654 | @deftypefun int getgrnam_r (const char *@var{name}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) | |
1655 | This function is similar to @code{getgrnam} in that is returns | |
1656 | information about the group whose group name is @var{name}. But the result | |
1657 | is not placed in a static buffer. Instead the user supplied structure | |
1658 | pointed to by @var{result_buf} is filled with the information. The | |
1659 | first @var{buflen} bytes of the additional buffer pointed to by | |
1660 | @var{buffer} are used to contain additional information, normally | |
1661 | strings which are pointed to by the elements of the result structure. | |
1662 | ||
1663 | If the return value is @code{0} the pointer returned in @var{result} | |
1664 | points to the record which contains the wanted data (i.e., @var{result} | |
26761c28 UD |
1665 | contains the value @var{result_buf}). If the return value is non-zero |
1666 | there is no group in the data base with group name @var{name} or the | |
ba1ffaa1 UD |
1667 | buffer @var{buffer} is too small to contain all the needed information. |
1668 | In the later case the global @var{errno} variable is set to | |
1669 | @code{ERANGE}. | |
1670 | @end deftypefun | |
1671 | ||
0413b54c | 1672 | @node Scanning All Groups |
28f540f4 RM |
1673 | @subsection Scanning the List of All Groups |
1674 | @cindex scanning the group list | |
1675 | ||
1676 | This section explains how a program can read the list of all groups in | |
1677 | the system, one group at a time. The functions described here are | |
1678 | declared in @file{grp.h}. | |
1679 | ||
1680 | You can use the @code{fgetgrent} function to read group entries from a | |
1681 | particular file. | |
1682 | ||
1683 | @comment grp.h | |
1684 | @comment SVID | |
1685 | @deftypefun {struct group *} fgetgrent (FILE *@var{stream}) | |
1686 | The @code{fgetgrent} function reads the next entry from @var{stream}. | |
1687 | It returns a pointer to the entry. The structure is statically | |
1688 | allocated and is rewritten on subsequent calls to @code{fgetgrent}. You | |
1689 | must copy the contents of the structure if you wish to save the | |
1690 | information. | |
1691 | ||
1692 | The stream must correspond to a file in the same format as the standard | |
1693 | group database file. | |
1694 | @end deftypefun | |
1695 | ||
ba1ffaa1 UD |
1696 | @comment grp.h |
1697 | @comment GNU | |
1698 | @deftypefun int fgetgrent_r (FILE *@var{stream}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) | |
1699 | This function is similar to @code{fgetgrent} in that it reads the next | |
1700 | user entry from @var{stream}. But the result is returned in the | |
1701 | structure pointed to by @var{result_buf}. The | |
1702 | first @var{buflen} bytes of the additional buffer pointed to by | |
1703 | @var{buffer} are used to contain additional information, normally | |
1704 | strings which are pointed to by the elements of the result structure. | |
1705 | ||
1706 | This stream must correspond to a file in the same format as the standard | |
1707 | group database file. | |
1708 | ||
26761c28 | 1709 | If the function returns zero @var{result} points to the structure with |
ba1ffaa1 | 1710 | the wanted data (normally this is in @var{result_buf}). If errors |
6d52618b | 1711 | occurred the return value is non-zero and @var{result} contains a null |
ba1ffaa1 UD |
1712 | pointer. |
1713 | @end deftypefun | |
1714 | ||
28f540f4 RM |
1715 | The way to scan all the entries in the group database is with |
1716 | @code{setgrent}, @code{getgrent}, and @code{endgrent}. | |
1717 | ||
1718 | @comment grp.h | |
1719 | @comment SVID, BSD | |
1720 | @deftypefun void setgrent (void) | |
1721 | This function initializes a stream for reading from the group data base. | |
ba1ffaa1 | 1722 | You use this stream by calling @code{getgrent} or @code{getgrent_r}. |
28f540f4 RM |
1723 | @end deftypefun |
1724 | ||
1725 | @comment grp.h | |
1726 | @comment SVID, BSD | |
1727 | @deftypefun {struct group *} getgrent (void) | |
1728 | The @code{getgrent} function reads the next entry from the stream | |
1729 | initialized by @code{setgrent}. It returns a pointer to the entry. The | |
1730 | structure is statically allocated and is rewritten on subsequent calls | |
1731 | to @code{getgrent}. You must copy the contents of the structure if you | |
1732 | wish to save the information. | |
1733 | @end deftypefun | |
1734 | ||
ba1ffaa1 UD |
1735 | @comment grp.h |
1736 | @comment GNU | |
1737 | @deftypefun int getgrent_r (struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result}) | |
1738 | This function is similar to @code{getgrent} in that it returns the next | |
1739 | entry from the stream initialized by @code{setgrent}. But in contrast | |
1740 | to the @code{getgrent} function this function is reentrant since the | |
1741 | result is placed in the user supplied structure pointed to by | |
1742 | @var{result_buf}. Additional data, normally the strings pointed to by | |
1743 | the elements of the result structure, are placed in the additional | |
1744 | buffer or length @var{buflen} starting at @var{buffer}. | |
1745 | ||
26761c28 | 1746 | If the function returns zero @var{result} points to the structure with |
ba1ffaa1 | 1747 | the wanted data (normally this is in @var{result_buf}). If errors |
6d52618b | 1748 | occurred the return value is non-zero and @var{result} contains a null |
ba1ffaa1 UD |
1749 | pointer. |
1750 | @end deftypefun | |
1751 | ||
28f540f4 RM |
1752 | @comment grp.h |
1753 | @comment SVID, BSD | |
1754 | @deftypefun void endgrent (void) | |
ba1ffaa1 UD |
1755 | This function closes the internal stream used by @code{getgrent} or |
1756 | @code{getgrent_r}. | |
1757 | @end deftypefun | |
1758 | ||
0413b54c | 1759 | @node Netgroup Database |
ba1ffaa1 UD |
1760 | @section Netgroup Database |
1761 | ||
1762 | @menu | |
1763 | * Netgroup Data:: Data in the Netgroup database and where | |
1764 | it comes from. | |
1765 | * Lookup Netgroup:: How to look for a particular netgroup. | |
1766 | * Netgroup Membership:: How to test for netgroup membership. | |
1767 | @end menu | |
1768 | ||
0413b54c | 1769 | @node Netgroup Data |
ba1ffaa1 UD |
1770 | @subsection Netgroup Data |
1771 | ||
2c6fe0bd | 1772 | @cindex Netgroup |
f2ea0f5b | 1773 | Sometimes it is useful group users according to other criteria like the |
ba1ffaa1 UD |
1774 | ones used in the @xref{Group Database}. E.g., it is useful to associate |
1775 | a certain group of users with a certain machine. On the other hand | |
1776 | grouping of host names is not supported so far. | |
1777 | ||
1778 | In Sun Microsystems SunOS appeared a new kind of database, the netgroup | |
1779 | database. It allows to group hosts, users, and domain freely, giving | |
1780 | them individual names. More concrete: a netgroup is a list of triples | |
1781 | consisting of a host name, a user name, and a domain name, where any of | |
1782 | the entries can be a wildcard entry, matching all inputs. A last | |
1783 | possibility is that names of other netgroups can also be given in the | |
6d52618b | 1784 | list specifying a netgroup. So one can construct arbitrary hierarchies |
ba1ffaa1 UD |
1785 | without loops. |
1786 | ||
1787 | Sun's implementation allows netgroups only for the @code{nis} or | |
1788 | @code{nisplus} service @pxref{Services in the NSS configuration}. The | |
1789 | implementation in the GNU C library has no such restriction. An entry | |
1790 | in either of the input services must have the following form: | |
1791 | ||
1792 | @smallexample | |
1793 | @var{groupname} ( @var{groupname} | @code{(}@var{hostname}@code{,}@var{username}@code{,}@code{domainname}@code{)} )+ | |
1794 | @end smallexample | |
1795 | ||
1796 | Any of the fields in the triple can be empty which means anything | |
26761c28 UD |
1797 | matches. While describing the functions we will see that the opposite |
1798 | case is useful as well. I.e., there may be entries which will not | |
ba1ffaa1 UD |
1799 | match any input. For entries like a name consisting of the single |
1800 | character @code{-} shall be used. | |
1801 | ||
0413b54c | 1802 | @node Lookup Netgroup |
ba1ffaa1 UD |
1803 | @subsection Looking up one Netgroup |
1804 | ||
1805 | The lookup functions for netgroups are a bit different to all other | |
1806 | system database handling functions. Since a single netgroup can contain | |
1807 | many entries a two-step process is needed. First a single netgroup is | |
1808 | selected and then one can iterate over all entries in this netgroup. | |
1809 | These functions are declared in @file{netdb.h}. | |
1810 | ||
1811 | @comment netdb.h | |
1812 | @deftypefun int setnetgrent (const char *@var{netgroup}) | |
1813 | A call to this function initializes the internal state of the library to | |
1814 | allow following calls of the @code{getnetgrent} iterate over all entries | |
1815 | in the netgroup with name @var{netgroup}. | |
1816 | ||
1817 | When the call is successful (i.e., when a netgroup with this name exist) | |
1818 | the return value is @code{1}. When the return value is @code{0} no | |
6d52618b | 1819 | netgroup of this name is known or some other error occurred. |
ba1ffaa1 UD |
1820 | @end deftypefun |
1821 | ||
1822 | It is important to remember that there is only one single state for | |
1823 | iterating the netgroups. Even if the programmer uses the | |
1824 | @code{getnetgrent_r} function the result is not really reentrant since | |
1825 | always only one single netgroup at a time can be processed. If the | |
1826 | program needs to process more than one netgroup simultaneously she | |
1827 | must protect this by using external locking. This problem was | |
1828 | introduced in the original netgroups implementation in SunOS and since | |
1829 | we must stay compatible it is not possible to change this. | |
1830 | ||
1831 | Some other functions also use the netgroups state. Currently these are | |
1832 | the @code{innetgr} function and parts of the implementation of the | |
1833 | @code{compat} service part of the NSS implementation. | |
1834 | ||
1835 | @comment netdb.h | |
1836 | @deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp}) | |
1837 | This function returns the next unprocessed entry of the currently | |
1838 | selected netgroup. The string pointers, which addresses are passed in | |
1839 | the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain | |
1840 | after a successful call pointers to appropriate strings. If the string | |
1841 | in the next entry is empty the pointer has the value @code{NULL}. | |
1842 | The returned string pointers are only valid unless no of the netgroup | |
1843 | related functions are called. | |
1844 | ||
1845 | The return value is @code{1} if the next entry was successfully read. A | |
6d52618b | 1846 | value of @code{0} means no further entries exist or internal errors occurred. |
ba1ffaa1 UD |
1847 | @end deftypefun |
1848 | ||
1849 | @comment netdb.h | |
1850 | @deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, int @var{buflen}) | |
1851 | This function is similar to @code{getnetgrent} with only one exception: | |
1852 | the strings the three string pointers @var{hostp}, @var{userp}, and | |
1853 | @var{domainp} point to, are placed in the buffer of @var{buflen} bytes | |
1854 | starting at @var{buffer}. This means the returned values are valid | |
1855 | even after other netgroup related functions are called. | |
1856 | ||
1857 | The return value is @code{1} if the next entry was successfully read and | |
1858 | the buffer contains enough room to place the strings in it. @code{0} is | |
1859 | returned in case no more entries are found, the buffer is too small, or | |
6d52618b | 1860 | internal errors occurred. |
ba1ffaa1 UD |
1861 | |
1862 | This function is a GNU extension. The original implementation in the | |
1863 | SunOS libc does not provide this function. | |
1864 | @end deftypefun | |
1865 | ||
1866 | @comment netdb.h | |
1867 | @deftypefun void endnetgrent (void) | |
1868 | This function free all buffers which were allocated to process the last | |
1869 | selected netgroup. As a result all string pointers returned by calls | |
1870 | to @code{getnetgrent} are invalid afterwards. | |
1871 | @end deftypefun | |
1872 | ||
0413b54c | 1873 | @node Netgroup Membership |
ba1ffaa1 UD |
1874 | @subsection Testing for Netgroup Membership |
1875 | ||
1876 | It is often not necessary to scan the whole netgroup since often the | |
1877 | only interesting question is whether a given entry is part of the | |
1878 | selected netgroup. | |
1879 | ||
1880 | @comment netdb.h | |
1881 | @deftypefun int innetgr (const char *@var{netgroup}, const char *@var{host}, const char *@var{user}, const char *@var{domain}) | |
1882 | This function tests whether the triple specified by the parameters | |
1883 | @var{hostp}, @var{userp}, and @var{domainp} is part of the netgroup | |
1884 | @var{netgroup}. Using this function has the advantage that | |
1885 | ||
1886 | @enumerate | |
1887 | @item | |
1888 | no other netgroup function can use the global netgroup state since | |
1889 | internal locking is used and | |
1890 | @item | |
1891 | the function is implemented more efficiently than successive calls | |
1892 | to the other @code{set}/@code{get}/@code{endnetgrent} functions. | |
1893 | @end enumerate | |
1894 | ||
1895 | Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be | |
1896 | @code{NULL} which means any value is excepted in this position. This is | |
1897 | also true for the name @code{-} which should not match any other string | |
1898 | otherwise. | |
1899 | ||
1900 | The return value is @code{1} if an entry matching the given triple is | |
26761c28 | 1901 | found in the netgroup. The return value is @code{0} if the netgroup |
ba1ffaa1 | 1902 | itself is not found, the netgroup does not contain the triple or |
6d52618b | 1903 | internal errors occurred. |
28f540f4 RM |
1904 | @end deftypefun |
1905 | ||
0413b54c | 1906 | @node Database Example |
28f540f4 RM |
1907 | @section User and Group Database Example |
1908 | ||
1909 | Here is an example program showing the use of the system database inquiry | |
1910 | functions. The program prints some information about the user running | |
1911 | the program. | |
1912 | ||
1913 | @smallexample | |
1914 | @include db.c.texi | |
1915 | @end smallexample | |
1916 | ||
1917 | Here is some output from this program: | |
1918 | ||
1919 | @smallexample | |
1920 | I am Throckmorton Snurd. | |
1921 | My login name is snurd. | |
1922 | My uid is 31093. | |
1923 | My home directory is /home/fsg/snurd. | |
1924 | My default shell is /bin/sh. | |
1925 | My default group is guest (12). | |
1926 | The members of this group are: | |
1927 | friedman | |
1928 | tami | |
1929 | @end smallexample |