summaryrefslogtreecommitdiff
path: root/manual/users.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/users.texi')
-rw-r--r--manual/users.texi364
1 files changed, 135 insertions, 229 deletions
diff --git a/manual/users.texi b/manual/users.texi
index e8f0f3bdf3..4ed79ba26f 100644
--- a/manual/users.texi
+++ b/manual/users.texi
@@ -152,7 +152,7 @@ by creating a new user ID and login name (say, @code{games}) to own the
scores file, and make the file writable only by this user. Then, when
the game program wants to update this file, it can change its effective
user ID to be that for @code{games}. In effect, the program must
-adopt the persona of @code{games} so it can write the scores file.
+adopt the persona of @code{games} so it can write to the scores file.
@node How Change Persona
@section How an Application Can Change Persona
@@ -204,53 +204,46 @@ facilities, you must include the header files @file{sys/types.h} and
@pindex unistd.h
@pindex sys/types.h
-@comment sys/types.h
-@comment POSIX.1
@deftp {Data Type} uid_t
+@standards{POSIX.1, sys/types.h}
This is an integer data type used to represent user IDs. In
@theglibc{}, this is an alias for @code{unsigned int}.
@end deftp
-@comment sys/types.h
-@comment POSIX.1
@deftp {Data Type} gid_t
+@standards{POSIX.1, sys/types.h}
This is an integer data type used to represent group IDs. In
@theglibc{}, this is an alias for @code{unsigned int}.
@end deftp
-@comment unistd.h
-@comment POSIX.1
@deftypefun uid_t getuid (void)
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@c Atomic syscall, except on hurd, where it takes a lock within a hurd
@c critical section.
The @code{getuid} function returns the real user ID of the process.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun gid_t getgid (void)
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{getgid} function returns the real group ID of the process.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun uid_t geteuid (void)
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{geteuid} function returns the effective user ID of the process.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun gid_t getegid (void)
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{getegid} function returns the effective group ID of the process.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun int getgroups (int @var{count}, gid_t *@var{groups})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
The @code{getgroups} function is used to inquire about the supplementary
group IDs of the process. Up to @var{count} of these group IDs are
@@ -295,9 +288,8 @@ include the header files @file{sys/types.h} and @file{unistd.h}.
@pindex unistd.h
@pindex sys/types.h
-@comment unistd.h
-@comment POSIX.1
@deftypefun int seteuid (uid_t @var{neweuid})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c seteuid @asulock @aculock
@c INLINE_SETXID_SYSCALL @asulock @aculock
@@ -350,14 +342,13 @@ Older systems (those without the @code{_POSIX_SAVED_IDS} feature) do not
have this function.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun int setuid (uid_t @var{newuid})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c setuid @asulock @aculock
@c INLINE_SETXID_SYSCALL dup @asulock @aculock
If the calling process is privileged, this function sets both the real
-and effective user ID of the process to @var{newuid}. It also deletes
+and effective user IDs of the process to @var{newuid}. It also deletes
the file user ID of the process, if any. @var{newuid} may be any
legal value. (Once this has been done, there is no way to recover the
old effective user ID.)
@@ -369,9 +360,8 @@ If the process is not privileged, and the system supports the
The return values and error conditions are the same as for @code{seteuid}.
@end deftypefun
-@comment unistd.h
-@comment BSD
@deftypefun int setreuid (uid_t @var{ruid}, uid_t @var{euid})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c setreuid @asulock @aculock
@c INLINE_SETXID_SYSCALL dup @asulock @aculock
@@ -407,9 +397,8 @@ the header files @file{sys/types.h} and @file{unistd.h}.
@pindex unistd.h
@pindex sys/types.h
-@comment unistd.h
-@comment POSIX.1
@deftypefun int setegid (gid_t @var{newgid})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c setegid @asulock @aculock
@c INLINE_SETXID_SYSCALL dup @asulock @aculock
@@ -429,9 +418,8 @@ as those for @code{seteuid}.
This function is only present if @code{_POSIX_SAVED_IDS} is defined.
@end deftypefun
-@comment unistd.h
-@comment POSIX.1
@deftypefun int setgid (gid_t @var{newgid})
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c setgid @asulock @aculock
@c INLINE_SETXID_SYSCALL dup @asulock @aculock
@@ -446,9 +434,8 @@ The return values and error conditions for @code{setgid} are the same
as those for @code{seteuid}.
@end deftypefun
-@comment unistd.h
-@comment BSD
@deftypefun int setregid (gid_t @var{rgid}, gid_t @var{egid})
+@standards{BSD, unistd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c setregid @asulock @aculock
@c INLINE_SETXID_SYSCALL dup @asulock @aculock
@@ -485,9 +472,8 @@ group IDs. To use @code{setgroups} or @code{initgroups}, your programs
should include the header file @file{grp.h}.
@pindex grp.h
-@comment grp.h
-@comment BSD
@deftypefun int setgroups (size_t @var{count}, const gid_t *@var{groups})
+@standards{BSD, grp.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
@c setgroups @asulock @aculock
@c INLINE_SETXID_SYSCALL dup @asulock @aculock
@@ -505,9 +491,8 @@ The calling process is not privileged.
@end table
@end deftypefun
-@comment grp.h
-@comment BSD
@deftypefun int initgroups (const char *@var{user}, gid_t @var{group})
+@standards{BSD, grp.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @acsmem{} @acsfd{} @aculock{}}}
@c initgroups @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c sysconf(_SC_NGROUPS_MAX) dup @acsfd
@@ -556,9 +541,8 @@ not want to change the process's supplementary group IDs, you can use
include the header file @file{grp.h}.
@pindex grp.h
-@comment grp.h
-@comment BSD
@deftypefun int getgrouplist (const char *@var{user}, gid_t @var{group}, gid_t *@var{groups}, int *@var{ngroups})
+@standards{BSD, grp.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @acsmem{} @acsfd{} @aculock{}}}
@c getgrouplist @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c MAX dup ok
@@ -879,9 +863,8 @@ The @code{getlogin} function is declared in @file{unistd.h}, while
@pindex stdio.h
@pindex unistd.h
-@comment unistd.h
-@comment POSIX.1
@deftypefun {char *} getlogin (void)
+@standards{POSIX.1, unistd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:getlogin} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getlogin (linux) @mtasurace:getlogin @mtasurace:utent @mtascusig:ALRM @mtascutimer @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c getlogin_r_loginuid dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@@ -924,9 +907,8 @@ is statically allocated and might be overwritten on subsequent calls to
this function or to @code{cuserid}.
@end deftypefun
-@comment stdio.h
-@comment POSIX.1
@deftypefun {char *} cuserid (char *@var{string})
+@standards{POSIX.1, stdio.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:cuserid/!string} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c cuserid @mtasurace:cuserid/!string @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c if string is NULL, cuserid will overwrite and return a static buffer
@@ -946,9 +928,8 @@ withdrawn in XPG4.2 and has already been removed from newer revisions of
POSIX.1.
@end deftypefun
-@comment stdio.h
-@comment POSIX.1
@deftypevr Macro int L_cuserid
+@standards{POSIX.1, stdio.h}
An integer constant that indicates how long an array you might need to
store a user name.
@end deftypevr
@@ -997,9 +978,8 @@ These functions and the corresponding data structures are declared in
the header file @file{utmp.h}.
@pindex utmp.h
-@comment utmp.h
-@comment SVID
@deftp {Data Type} {struct exit_status}
+@standards{SVID, utmp.h}
The @code{exit_status} data structure is used to hold information about
the exit status of processes marked as @code{DEAD_PROCESS} in the user
accounting database.
@@ -1059,7 +1039,7 @@ The Internet address of a remote host.
The @code{ut_type}, @code{ut_pid}, @code{ut_id}, @code{ut_tv}, and
@code{ut_host} fields are not available on all systems. Portable
applications therefore should be prepared for these situations. To help
-doing this the @file{utmp.h} header provides macros
+do this the @file{utmp.h} header provides macros
@code{_HAVE_UT_TYPE}, @code{_HAVE_UT_PID}, @code{_HAVE_UT_ID},
@code{_HAVE_UT_TV}, and @code{_HAVE_UT_HOST} if the respective field is
available. The programmer can handle the situations by using
@@ -1069,68 +1049,48 @@ The following macros are defined for use as values for the
@code{ut_type} member of the @code{utmp} structure. The values are
integer constants.
-@table @code
-@comment utmp.h
-@comment SVID
-@vindex EMPTY
+@vtable @code
@item EMPTY
+@standards{SVID, utmp.h}
This macro is used to indicate that the entry contains no valid user
accounting information.
-@comment utmp.h
-@comment SVID
-@vindex RUN_LVL
@item RUN_LVL
-This macro is used to identify the systems runlevel.
+@standards{SVID, utmp.h}
+This macro is used to identify the system's runlevel.
-@comment utmp.h
-@comment SVID
-@vindex BOOT_TIME
@item BOOT_TIME
+@standards{SVID, utmp.h}
This macro is used to identify the time of system boot.
-@comment utmp.h
-@comment SVID
-@vindex OLD_TIME
@item OLD_TIME
+@standards{SVID, utmp.h}
This macro is used to identify the time when the system clock changed.
-@comment utmp.h
-@comment SVID
-@vindex NEW_TIME
@item NEW_TIME
-This macro is used to identify the time after the system changed.
+@standards{SVID, utmp.h}
+This macro is used to identify the time after the system clock changed.
-@comment utmp.h
-@comment SVID
-@vindex INIT_PROCESS
@item INIT_PROCESS
+@standards{SVID, utmp.h}
This macro is used to identify a process spawned by the init process.
-@comment utmp.h
-@comment SVID
-@vindex LOGIN_PROCESS
@item LOGIN_PROCESS
+@standards{SVID, utmp.h}
This macro is used to identify the session leader of a logged in user.
-@comment utmp.h
-@comment SVID
-@vindex USER_PROCESS
@item USER_PROCESS
+@standards{SVID, utmp.h}
This macro is used to identify a user process.
-@comment utmp.h
-@comment SVID
-@vindex DEAD_PROCESS
@item DEAD_PROCESS
+@standards{SVID, utmp.h}
This macro is used to identify a terminated process.
-@comment utmp.h
-@comment SVID
-@vindex ACCOUNTING
@item ACCOUNTING
+@standards{SVID, utmp.h}
???
-@end table
+@end vtable
The size of the @code{ut_line}, @code{ut_id}, @code{ut_user} and
@code{ut_host} arrays can be found using the @code{sizeof} operator.
@@ -1141,9 +1101,8 @@ the time associated with the entry. Therefore, for backwards
compatibility only, @file{utmp.h} defines @code{ut_time} as an alias for
@code{ut_tv.tv_sec}.
-@comment utmp.h
-@comment SVID
@deftypefun void setutent (void)
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
@c Besides the static variables in utmp_file.c, there's the jump_table.
@c They're both modified while holding a lock, but other threads may
@@ -1168,9 +1127,8 @@ If the database is already open, it resets the input to the beginning of
the database.
@end deftypefun
-@comment utmp.h
-@comment SVID
@deftypefun {struct utmp *} getutent (void)
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtasurace{:utentbuf} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c The static buffer that holds results is allocated with malloc at
@c the first call; the test is not thread-safe, so multiple concurrent
@@ -1189,9 +1147,8 @@ function which stores the data in a user-provided buffer.
A null pointer is returned in case no further entry is available.
@end deftypefun
-@comment utmp.h
-@comment SVID
@deftypefun void endutent (void)
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
@c endutent @mtasurace:utent @asulock @aculock @acsfd
@c libc_lock_lock dup @asulock @aculock
@@ -1203,9 +1160,8 @@ A null pointer is returned in case no further entry is available.
This function closes the user accounting database.
@end deftypefun
-@comment utmp.h
-@comment SVID
@deftypefun {struct utmp *} getutid (const struct utmp *@var{id})
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
@c Same caveats as getutline.
@c
@@ -1240,9 +1196,8 @@ is necessary to zero out the static data after each call. Otherwise
over again.
@end deftypefun
-@comment utmp.h
-@comment SVID
@deftypefun {struct utmp *} getutline (const struct utmp *@var{line})
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c The static buffer that holds results is allocated with malloc at
@c the first call; the test is not thread-safe, so multiple concurrent
@@ -1270,9 +1225,8 @@ is necessary to zero out the static data after each call. Otherwise
over again.
@end deftypefun
-@comment utmp.h
-@comment SVID
@deftypefun {struct utmp *} pututline (const struct utmp *@var{utmp})
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
@c pututline @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
@c libc_lock_lock dup @asulock @aculock
@@ -1323,9 +1277,8 @@ return value data in another thread. Therefore @theglibc{}
provides as extensions three more functions which return the data in a
user-provided buffer.
-@comment utmp.h
-@comment GNU
@deftypefun int getutent_r (struct utmp *@var{buffer}, struct utmp **@var{result})
+@standards{GNU, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
@c getutent_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
@c libc_lock_lock dup @asulock @aculock
@@ -1361,9 +1314,8 @@ execution of @code{getutent_r} the function returns @code{-1}.
This function is a GNU extension.
@end deftypefun
-@comment utmp.h
-@comment GNU
@deftypefun int getutid_r (const struct utmp *@var{id}, struct utmp *@var{buffer}, struct utmp **@var{result})
+@standards{GNU, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
@c getutid_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
@c libc_lock_lock dup @asulock @aculock
@@ -1392,9 +1344,8 @@ successful the function return @code{-1}.
This function is a GNU extension.
@end deftypefun
-@comment utmp.h
-@comment GNU
@deftypefun int getutline_r (const struct utmp *@var{line}, struct utmp *@var{buffer}, struct utmp **@var{result})
+@standards{GNU, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
@c getutline_r @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @aculock @acsfd
@c libc_lock_lock dup @asulock @aculock
@@ -1437,9 +1388,8 @@ previous logins (usually in @file{/etc/wtmp} or @file{/var/log/wtmp}).
For specifying which database to examine, the following function should
be used.
-@comment utmp.h
-@comment SVID
@deftypefun int utmpname (const char *@var{file})
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
@c utmpname @mtasurace:utent @asulock @ascuheap @aculock @acsmem
@c libc_lock_lock dup @asulock @aculock
@@ -1473,9 +1423,8 @@ database can be successfully opened.
Specially for maintaining log-like databases @theglibc{} provides
the following function:
-@comment utmp.h
-@comment SVID
@deftypefun void updwtmp (const char *@var{wtmp_file}, const struct utmp *@var{utmp})
+@standards{SVID, utmp.h}
@safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}}
@c updwtmp @mtascusig:ALRM @mtascutimer @acsfd
@c TRANSFORM_UTMP_FILE_NAME dup ok
@@ -1547,112 +1496,88 @@ The following macros are defined for use as values for the
integer constants and are, in @theglibc{}, identical to the
definitions in @file{utmp.h}.
-@table @code
-@comment utmpx.h
-@comment XPG4.2
-@vindex EMPTY
+@vtable @code
@item EMPTY
+@standards{XPG4.2, utmpx.h}
This macro is used to indicate that the entry contains no valid user
accounting information.
-@comment utmpx.h
-@comment XPG4.2
-@vindex RUN_LVL
@item RUN_LVL
-This macro is used to identify the systems runlevel.
+@standards{XPG4.2, utmpx.h}
+This macro is used to identify the system's runlevel.
-@comment utmpx.h
-@comment XPG4.2
-@vindex BOOT_TIME
@item BOOT_TIME
+@standards{XPG4.2, utmpx.h}
This macro is used to identify the time of system boot.
-@comment utmpx.h
-@comment XPG4.2
-@vindex OLD_TIME
@item OLD_TIME
+@standards{XPG4.2, utmpx.h}
This macro is used to identify the time when the system clock changed.
-@comment utmpx.h
-@comment XPG4.2
-@vindex NEW_TIME
@item NEW_TIME
-This macro is used to identify the time after the system changed.
+@standards{XPG4.2, utmpx.h}
+This macro is used to identify the time after the system clock changed.
-@comment utmpx.h
-@comment XPG4.2
-@vindex INIT_PROCESS
@item INIT_PROCESS
+@standards{XPG4.2, utmpx.h}
This macro is used to identify a process spawned by the init process.
-@comment utmpx.h
-@comment XPG4.2
-@vindex LOGIN_PROCESS
@item LOGIN_PROCESS
+@standards{XPG4.2, utmpx.h}
This macro is used to identify the session leader of a logged in user.
-@comment utmpx.h
-@comment XPG4.2
-@vindex USER_PROCESS
@item USER_PROCESS
+@standards{XPG4.2, utmpx.h}
This macro is used to identify a user process.
-@comment utmpx.h
-@comment XPG4.2
-@vindex DEAD_PROCESS
@item DEAD_PROCESS
+@standards{XPG4.2, utmpx.h}
This macro is used to identify a terminated process.
-@end table
+@end vtable
The size of the @code{ut_line}, @code{ut_id} and @code{ut_user} arrays
can be found using the @code{sizeof} operator.
-@comment utmpx.h
-@comment XPG4.2
@deftypefun void setutxent (void)
+@standards{XPG4.2, utmpx.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
This function is similar to @code{setutent}. In @theglibc{} it is
simply an alias for @code{setutent}.
@end deftypefun
-@comment utmpx.h
-@comment XPG4.2
@deftypefun {struct utmpx *} getutxent (void)
+@standards{XPG4.2, utmpx.h}
@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
The @code{getutxent} function is similar to @code{getutent}, but returns
a pointer to a @code{struct utmpx} instead of @code{struct utmp}. In
@theglibc{} it simply is an alias for @code{getutent}.
@end deftypefun
-@comment utmpx.h
-@comment XPG4.2
@deftypefun void endutxent (void)
+@standards{XPG4.2, utmpx.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
This function is similar to @code{endutent}. In @theglibc{} it is
simply an alias for @code{endutent}.
@end deftypefun
-@comment utmpx.h
-@comment XPG4.2
@deftypefun {struct utmpx *} getutxid (const struct utmpx *@var{id})
+@standards{XPG4.2, utmpx.h}
@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{} @acsfd{}}}
This function is similar to @code{getutid}, but uses @code{struct utmpx}
instead of @code{struct utmp}. In @theglibc{} it is simply an alias
for @code{getutid}.
@end deftypefun
-@comment utmpx.h
-@comment XPG4.2
@deftypefun {struct utmpx *} getutxline (const struct utmpx *@var{line})
+@standards{XPG4.2, utmpx.h}
@safety{@prelim{}@mtunsafe{@mtuinit{} @mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
This function is similar to @code{getutid}, but uses @code{struct utmpx}
instead of @code{struct utmp}. In @theglibc{} it is simply an alias
for @code{getutline}.
@end deftypefun
-@comment utmpx.h
-@comment XPG4.2
@deftypefun {struct utmpx *} pututxline (const struct utmpx *@var{utmp})
+@standards{XPG4.2, utmpx.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{}}}
The @code{pututxline} function is functionally identical to
@code{pututline}, but uses @code{struct utmpx} instead of @code{struct
@@ -1660,9 +1585,8 @@ utmp}. In @theglibc{}, @code{pututxline} is simply an alias for
@code{pututline}.
@end deftypefun
-@comment utmpx.h
-@comment XPG4.2
@deftypefun int utmpxname (const char *@var{file})
+@standards{XPG4.2, utmpx.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsmem{}}}
The @code{utmpxname} function is functionally identical to
@code{utmpname}. In @theglibc{}, @code{utmpxname} is simply an
@@ -1674,19 +1598,17 @@ You can translate between a traditional @code{struct utmp} and an XPG
these functions are merely copies, since the two structures are
identical.
-@comment utmpx.h
-@comment utmp.h
-@comment GNU
@deftypefun int getutmp (const struct utmpx *@var{utmpx}, struct utmp *@var{utmp})
+@standards{GNU, utmp.h}
+@standards{GNU, utmpx.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{getutmp} copies the information, insofar as the structures are
compatible, from @var{utmpx} to @var{utmp}.
@end deftypefun
-@comment utmpx.h
-@comment utmp.h
-@comment GNU
@deftypefun int getutmpx (const struct utmp *@var{utmp}, struct utmpx *@var{utmpx})
+@standards{GNU, utmp.h}
+@standards{GNU, utmpx.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@code{getutmpx} copies the information, insofar as the structures are
compatible, from @var{utmp} to @var{utmpx}.
@@ -1704,9 +1626,8 @@ Note that the @code{ut_user} member of @code{struct utmp} is called
@code{ut_name} in BSD. Therefore, @code{ut_name} is defined as an alias
for @code{ut_user} in @file{utmp.h}.
-@comment utmp.h
-@comment BSD
@deftypefun int login_tty (int @var{filedes})
+@standards{BSD, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:ttyname}}@asunsafe{@ascuheap{} @asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c If this function is canceled, it may have succeeded in redirecting
@c only some of the standard streams to the newly opened terminal.
@@ -1726,9 +1647,8 @@ This function returns @code{0} on successful completion, and @code{-1}
on error.
@end deftypefun
-@comment utmp.h
-@comment BSD
@deftypefun void login (const struct utmp *@var{entry})
+@standards{BSD, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acucorrupt{} @acsfd{} @acsmem{}}}
@c login @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @ascuheap @aculock @acucorrupt @acsfd @acsmem
@c getpid dup ok
@@ -1759,9 +1679,8 @@ process. The remaining entries are copied from @var{entry}.
A copy of the entry is written to the user accounting log file.
@end deftypefun
-@comment utmp.h
-@comment BSD
@deftypefun int logout (const char *@var{ut_line})
+@standards{BSD, utmp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:utent} @mtascusig{:ALRM} @mtascutimer{}}@asunsafe{@asulock{} @ascuheap{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
@c logout @mtasurace:utent @mtascusig:ALRM @mtascutimer @asulock @ascuheap @aculock @acsfd @acsmem
@c utmpname dup @mtasurace:utent @asulock @ascuheap @aculock @acsmem
@@ -1780,9 +1699,8 @@ The @code{logout} function returns @code{1} if the entry was successfully
written to the database, or @code{0} on error.
@end deftypefun
-@comment utmp.h
-@comment BSD
@deftypefun void logwtmp (const char *@var{ut_line}, const char *@var{ut_name}, const char *@var{ut_host})
+@standards{BSD, utmp.h}
@safety{@prelim{}@mtunsafe{@mtascusig{:ALRM} @mtascutimer{}}@asunsafe{}@acunsafe{@acsfd{}}}
@c logwtmp @mtascusig:ALRM @mtascutimer @acsfd
@c memset dup ok
@@ -1812,6 +1730,16 @@ users. The database itself is kept in the file @file{/etc/passwd} on
most systems, but on some systems a special network server gives access
to it.
+Historically, this database included one-way hashes of user
+passphrases (@pxref{Passphrase Storage}) as well as public information
+about each user (such as their user ID and full name). Many of the
+functions and data structures associated with this database, and the
+filename @file{/etc/passwd} itself, reflect this history. However,
+the information in this database is available to all users, and it is
+no longer considered safe to make passphrase hashes available to all
+users, so they have been moved to a ``shadow'' database that can only
+be accessed with special privileges.
+
@menu
* User Data Structure:: What each user record contains.
* Lookup User:: How to look for a particular user.
@@ -1826,9 +1754,8 @@ The functions and data structures for accessing the system user database
are declared in the header file @file{pwd.h}.
@pindex pwd.h
-@comment pwd.h
-@comment POSIX.1
@deftp {Data Type} {struct passwd}
+@standards{POSIX.1, pwd.h}
The @code{passwd} data structure is used to hold information about
entries in the system user data base. It has at least the following members:
@@ -1836,8 +1763,10 @@ entries in the system user data base. It has at least the following members:
@item char *pw_name
The user's login name.
-@item char *pw_passwd.
-The encrypted password string.
+@item char *pw_passwd
+Historically, this field would hold the one-way hash of the user's
+passphrase. Nowadays, it will almost always be the single character
+@samp{x}, indicating that the hash is in the shadow database.
@item uid_t pw_uid
The user ID number.
@@ -1869,9 +1798,8 @@ You can search the system user database for information about a
specific user using @code{getpwuid} or @code{getpwnam}. These
functions are declared in @file{pwd.h}.
-@comment pwd.h
-@comment POSIX.1
@deftypefun {struct passwd *} getpwuid (uid_t @var{uid})
+@standards{POSIX.1, pwd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:pwuid} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getpwuid @mtasurace:pwuid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock dup @asulock @aculock
@@ -1888,9 +1816,8 @@ A null pointer value indicates there is no user in the data base with
user ID @var{uid}.
@end deftypefun
-@comment pwd.h
-@comment POSIX.1c
@deftypefun int getpwuid_r (uid_t @var{uid}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@standards{POSIX.1c, pwd.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getpwuid_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c nscd_getpwuid_r @ascuheap @acsfd @acsmem
@@ -2112,9 +2039,8 @@ error code @code{ERANGE} is returned and @var{errno} is set to
@end deftypefun
-@comment pwd.h
-@comment POSIX.1
@deftypefun {struct passwd *} getpwnam (const char *@var{name})
+@standards{POSIX.1, pwd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:pwnam} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getpwnam @mtasurace:pwnam @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock dup @asulock @aculock
@@ -2131,9 +2057,8 @@ This structure may be overwritten on subsequent calls to
A null pointer return indicates there is no user named @var{name}.
@end deftypefun
-@comment pwd.h
-@comment POSIX.1c
@deftypefun int getpwnam_r (const char *@var{name}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@standards{POSIX.1c, pwd.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getpwnam_r @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c nscd_getpwnam_r @ascuheap @asulock @aculock @acsfd @acsmem
@@ -2153,7 +2078,7 @@ A null pointer return indicates there is no user named @var{name}.
@c
@c _nss_*_getpwnam_r (assumed) @asuinit @asulock @acucorrupt @aculock
-This function is similar to @code{getpwnam} in that is returns
+This function is similar to @code{getpwnam} in that it returns
information about the user whose user name is @var{name}. However, like
@code{getpwuid_r}, it fills the user supplied buffers in
@var{result_buf} and @var{buffer} with the information instead of using
@@ -2174,9 +2099,8 @@ declared in @file{pwd.h}.
You can use the @code{fgetpwent} function to read user entries from a
particular file.
-@comment pwd.h
-@comment SVID
@deftypefun {struct passwd *} fgetpwent (FILE *@var{stream})
+@standards{SVID, pwd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:fpwent}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{}}}
@c fgetpwent @mtasurace:fpwent @asucorrupt @asulock @acucorrupt @aculock
@c fgetpos dup @asucorrupt @aculock @acucorrupt
@@ -2193,12 +2117,11 @@ rewritten on subsequent calls to @code{fgetpwent}. You must copy the
contents of the structure if you wish to save the information.
The stream must correspond to a file in the same format as the standard
-password database file.
+user database file.
@end deftypefun
-@comment pwd.h
-@comment GNU
@deftypefun int fgetpwent_r (FILE *@var{stream}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@standards{GNU, pwd.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
@c fgetpwent_r @asucorrupt @acucorrupt @aculock
@c flockfile dup @aculock
@@ -2215,7 +2138,7 @@ first @var{buflen} bytes of the additional buffer pointed to by
strings which are pointed to by the elements of the result structure.
The stream must correspond to a file in the same format as the standard
-password database file.
+user database file.
If the function returns zero @var{result} points to the structure with
the wanted data (normally this is in @var{result_buf}). If errors
@@ -2226,9 +2149,9 @@ pointer.
The way to scan all the entries in the user database is with
@code{setpwent}, @code{getpwent}, and @code{endpwent}.
-@comment pwd.h
-@comment SVID, BSD
@deftypefun void setpwent (void)
+@standards{SVID, pwd.h}
+@standards{BSD, pwd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c setpwent @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock @asulock @aculock
@@ -2244,9 +2167,8 @@ This function initializes a stream which @code{getpwent} and
@code{getpwent_r} use to read the user database.
@end deftypefun
-@comment pwd.h
-@comment POSIX.1
@deftypefun {struct passwd *} getpwent (void)
+@standards{POSIX.1, pwd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtasurace{:pwentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getpwent @mtasurace:pwent @mtasurace:pwentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock dup @asulock @aculock
@@ -2265,9 +2187,8 @@ wish to save the information.
A null pointer is returned when no more entries are available.
@end deftypefun
-@comment pwd.h
-@comment GNU
@deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+@standards{GNU, pwd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c The static buffer here is not the result_buf, but rather the
@c variables that keep track of what nss backend we've last used, and
@@ -2291,9 +2212,9 @@ The return values are the same as for @code{fgetpwent_r}.
@end deftypefun
-@comment pwd.h
-@comment SVID, BSD
@deftypefun void endpwent (void)
+@standards{SVID, pwd.h}
+@standards{BSD, pwd.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:pwent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c endpwent @mtasurace:pwent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock @asulock @aculock
@@ -2310,9 +2231,8 @@ This function closes the internal stream used by @code{getpwent} or
@node Writing a User Entry
@subsection Writing a User Entry
-@comment pwd.h
-@comment SVID
@deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream})
+@standards{SVID, pwd.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{}}@acunsafe{@aculock{} @acucorrupt{}}}
@c putpwent @mtslocale @asucorrupt @aculock @acucorrupt
@c fprintf dup @mtslocale @asucorrupt @aculock @acucorrupt [no @ascuheap @acsmem]
@@ -2326,7 +2246,6 @@ avoid using it, because it makes sense only on the assumption that the
on a system which merges the traditional Unix data base with other
extended information about users, adding an entry using this function
would inevitably leave out much of the important information.
-@c Then how are programmers to modify the password file? -zw
The group and user ID fields are left empty if the group or user name
starts with a - or +.
@@ -2357,9 +2276,8 @@ The functions and data structures for accessing the system group
database are declared in the header file @file{grp.h}.
@pindex grp.h
-@comment grp.h
-@comment POSIX.1
@deftp {Data Type} {struct group}
+@standards{POSIX.1, grp.h}
The @code{group} structure is used to hold information about an entry in
the system group database. It has at least the following members:
@@ -2386,9 +2304,8 @@ You can search the group database for information about a specific
group using @code{getgrgid} or @code{getgrnam}. These functions are
declared in @file{grp.h}.
-@comment grp.h
-@comment POSIX.1
@deftypefun {struct group *} getgrgid (gid_t @var{gid})
+@standards{POSIX.1, grp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:grgid} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getgrgid =~ getpwuid dup @mtasurace:grgid @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c getgrgid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@@ -2400,9 +2317,8 @@ This structure may be overwritten by subsequent calls to
A null pointer indicates there is no group with ID @var{gid}.
@end deftypefun
-@comment grp.h
-@comment POSIX.1c
@deftypefun int getgrgid_r (gid_t @var{gid}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@standards{POSIX.1c, grp.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getgrgid_r =~ getpwuid_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c nscd_getgrgid_r @ascuheap @acsfd @acsmem
@@ -2441,9 +2357,9 @@ error code @code{ERANGE} is returned and @var{errno} is set to
@code{ERANGE}.
@end deftypefun
-@comment grp.h
-@comment SVID, BSD
@deftypefun {struct group *} getgrnam (const char *@var{name})
+@standards{SVID, grp.h}
+@standards{BSD, grp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:grnam} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getgrnam =~ getpwnam dup @mtasurace:grnam @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c getgrnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@@ -2455,9 +2371,8 @@ This structure may be overwritten by subsequent calls to
A null pointer indicates there is no group named @var{name}.
@end deftypefun
-@comment grp.h
-@comment POSIX.1c
@deftypefun int getgrnam_r (const char *@var{name}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@standards{POSIX.1c, grp.h}
@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getgrnam_r =~ getpwnam_r dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c nscd_getgrnam_r @ascuheap @asulock @aculock @acsfd @acsmem
@@ -2466,13 +2381,12 @@ A null pointer indicates there is no group named @var{name}.
@c nss_group_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c *fct.l @ascuplugin
@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
-This function is similar to @code{getgrnam} in that is returns
+This function is similar to @code{getgrnam} in that it returns
information about the group whose group name is @var{name}. Like
@code{getgrgid_r}, it uses the user supplied buffers in
@var{result_buf} and @var{buffer}, not a static buffer.
-The return values are the same as for @code{getgrgid_r}
-@code{ERANGE}.
+The return values are the same as for @code{getgrgid_r}.
@end deftypefun
@node Scanning All Groups
@@ -2486,9 +2400,8 @@ declared in @file{grp.h}.
You can use the @code{fgetgrent} function to read group entries from a
particular file.
-@comment grp.h
-@comment SVID
@deftypefun {struct group *} fgetgrent (FILE *@var{stream})
+@standards{SVID, grp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:fgrent}}@asunsafe{@asucorrupt{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{}}}
@c fgetgrent @mtasurace:fgrent @asucorrupt @asulock @acucorrupt @aculock
@c fgetpos dup @asucorrupt @aculock @acucorrupt
@@ -2509,9 +2422,8 @@ The stream must correspond to a file in the same format as the standard
group database file.
@end deftypefun
-@comment grp.h
-@comment GNU
@deftypefun int fgetgrent_r (FILE *@var{stream}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@standards{GNU, grp.h}
@safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}}
@c fgetgrent_r @asucorrupt @acucorrupt @aculock
@c flockfile dup @aculock
@@ -2539,9 +2451,9 @@ pointer.
The way to scan all the entries in the group database is with
@code{setgrent}, @code{getgrent}, and @code{endgrent}.
-@comment grp.h
-@comment SVID, BSD
@deftypefun void setgrent (void)
+@standards{SVID, grp.h}
+@standards{BSD, grp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c setgrent =~ setpwent dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c ...*lookup_fct = nss_group_lookup2 dup @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@@ -2549,9 +2461,9 @@ This function initializes a stream for reading from the group data base.
You use this stream by calling @code{getgrent} or @code{getgrent_r}.
@end deftypefun
-@comment grp.h
-@comment SVID, BSD
@deftypefun {struct group *} getgrent (void)
+@standards{SVID, grp.h}
+@standards{BSD, grp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtasurace{:grentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getgrent =~ getpwent dup @mtasurace:grent @mtasurace:grentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c *func = getgrent_r dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@@ -2562,24 +2474,23 @@ to @code{getgrent}. You must copy the contents of the structure if you
wish to save the information.
@end deftypefun
-@comment grp.h
-@comment GNU
@deftypefun int getgrent_r (struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+@standards{GNU, grp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getgrent_r =~ getpwent_r dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
This function is similar to @code{getgrent} in that it returns the next
entry from the stream initialized by @code{setgrent}. Like
@code{fgetgrent_r}, it places the result in user-supplied buffers
-pointed to @var{result_buf} and @var{buffer}.
+pointed to by @var{result_buf} and @var{buffer}.
If the function returns zero @var{result} contains a pointer to the data
(normally equal to @var{result_buf}). If errors occurred the return
value is non-zero and @var{result} contains a null pointer.
@end deftypefun
-@comment grp.h
-@comment SVID, BSD
@deftypefun void endgrent (void)
+@standards{SVID, grp.h}
+@standards{BSD, grp.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:grent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c endgrent =~ endpwent dup @mtasurace:grent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
This function closes the internal stream used by @code{getgrent} or
@@ -2630,7 +2541,7 @@ Sometimes it is useful to group users according to other criteria
group of users with a certain machine. On the other hand grouping of
host names is not supported so far.
-In Sun Microsystems SunOS appeared a new kind of database, the netgroup
+In Sun Microsystems' SunOS appeared a new kind of database, the netgroup
database. It allows grouping hosts, users, and domains freely, giving
them individual names. To be more concrete, a netgroup is a list of triples
consisting of a host name, a user name, and a domain name where any of
@@ -2657,15 +2568,14 @@ character @code{-} shall be used.
@node Lookup Netgroup
@subsection Looking up one Netgroup
-The lookup functions for netgroups are a bit different to all other
+The lookup functions for netgroups are a bit different than all other
system database handling functions. Since a single netgroup can contain
many entries a two-step process is needed. First a single netgroup is
selected and then one can iterate over all entries in this netgroup.
These functions are declared in @file{netdb.h}.
-@comment netdb.h
-@comment BSD
@deftypefun int setnetgrent (const char *@var{netgroup})
+@standards{BSD, netdb.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c setnetgrent @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock dup @asulock @aculock
@@ -2701,7 +2611,7 @@ These functions are declared in @file{netdb.h}.
@c memcpy dup ok
@c libc_lock_unlock dup @aculock
A call to this function initializes the internal state of the library to
-allow following calls of the @code{getnetgrent} to iterate over all entries
+allow following calls of @code{getnetgrent} to iterate over all entries
in the netgroup with name @var{netgroup}.
When the call is successful (i.e., when a netgroup with this name exists)
@@ -2722,9 +2632,8 @@ Some other functions also use the netgroups state. Currently these are
the @code{innetgr} function and parts of the implementation of the
@code{compat} service part of the NSS implementation.
-@comment netdb.h
-@comment BSD
@deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp})
+@standards{BSD, netdb.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtasurace{:netgrentbuf} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getnetgrent @mtasurace:netgrent @mtasurace:netgrentbuf @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c uses unsafely a static buffer allocated within a libc_once call
@@ -2743,9 +2652,8 @@ The return value is @code{1} if the next entry was successfully read. A
value of @code{0} means no further entries exist or internal errors occurred.
@end deftypefun
-@comment netdb.h
-@comment GNU
@deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, size_t @var{buflen})
+@standards{GNU, netdb.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c getnetgrent_r @mtasurace:netgrent @mtslocale @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock dup @asulock @aculock
@@ -2774,9 +2682,8 @@ This function is a GNU extension. The original implementation in the
SunOS libc does not provide this function.
@end deftypefun
-@comment netdb.h
-@comment BSD
@deftypefun void endnetgrent (void)
+@standards{BSD, netdb.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c endnetgrent @mtasurace:netgrent @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c libc_lock_lock dup @asulock @aculock
@@ -2796,9 +2703,8 @@ It is often not necessary to scan the whole netgroup since often the
only interesting question is whether a given entry is part of the
selected netgroup.
-@comment netdb.h
-@comment BSD
@deftypefun int innetgr (const char *@var{netgroup}, const char *@var{host}, const char *@var{user}, const char *@var{domain})
+@standards{BSD, netdb.h}
@safety{@prelim{}@mtunsafe{@mtasurace{:netgrent} @mtslocale{}}@asunsafe{@ascudlopen{} @ascuplugin{} @ascuheap{} @asulock{}}@acunsafe{@acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
@c This function does not use the static data structure that the
@c *netgrent* ones do, but since each nss must maintains internal state
@@ -2831,7 +2737,7 @@ selected netgroup.
@c nss_next2 dup @ascudlopen @ascuplugin @ascuheap @asulock @acucorrupt @aculock @acsfd @acsmem
@c free_memory dup @ascuheap @acsmem
This function tests whether the triple specified by the parameters
-@var{hostp}, @var{userp}, and @var{domainp} is part of the netgroup
+@var{host}, @var{user}, and @var{domain} is part of the netgroup
@var{netgroup}. Using this function has the advantage that
@enumerate
@@ -2843,7 +2749,7 @@ the function is implemented more efficiently than successive calls
to the other @code{set}/@code{get}/@code{endnetgrent} functions.
@end enumerate
-Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be
+Any of the pointers @var{host}, @var{user}, or @var{domain} can be
@code{NULL} which means any value is accepted in this position. This is
also true for the name @code{-} which should not match any other string
otherwise.
generated by cgit v1.2.3 (git 2.39.1) at 2024-06-10 10:23:54 +0000