diff options
Diffstat (limited to 'lib/libc')
| -rw-r--r-- | lib/libc/gen/Makefile.inc | 8 | ||||
| -rw-r--r-- | lib/libc/gen/getpwent.3 | 138 | ||||
| -rw-r--r-- | lib/libc/gen/getpwnam.3 | 213 |
3 files changed, 252 insertions, 107 deletions
diff --git a/lib/libc/gen/Makefile.inc b/lib/libc/gen/Makefile.inc index a9ebf74aeaa..e88bd1bd6ed 100644 --- a/lib/libc/gen/Makefile.inc +++ b/lib/libc/gen/Makefile.inc @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile.inc,v 1.46 2009/04/21 09:34:51 martynas Exp $ +# $OpenBSD: Makefile.inc,v 1.47 2009/06/01 21:52:03 millert Exp $ # gen sources .PATH: ${LIBCSRCDIR}/arch/${MACHINE_ARCH}/gen ${LIBCSRCDIR}/gen @@ -51,6 +51,7 @@ MAN+= alarm.3 auth_subr.3 authenticate.3 basename.3 clock.3 confstr.3 \ getbsize.3 getcap.3 getcwd.3 getdomainname.3 getdiskbyname.3 \ getfsent.3 getgrent.3 getgrouplist.3 gethostname.3 getloadavg.3 \ getmntinfo.3 getnetgrent.3 getpagesize.3 getpass.3 getpwent.3 \ + getpwnam.3 \ getttyent.3 getusershell.3 glob.3 initgroups.3 isalnum.3 isalpha.3 \ isascii.3 isblank.3 iscntrl.3 isdigit.3 isfdtype.3 isgraph.3 \ isgreater.3 islower.3 isprint.3 ispunct.3 isspace.3 isupper.3 \ @@ -107,9 +108,8 @@ MLINKS+=getgrent.3 endgrent.3 getgrent.3 setgroupent.3 getgrent.3 getgrgid.3 \ MLINKS+=gethostname.3 sethostname.3 MLINKS+=getnetgrent.3 endnetgrent.3 getnetgrent.3 innetgr.3 \ getnetgrent.3 setnetgrent.3 -MLINKS+=getpwent.3 endpwent.3 getpwent.3 setpassent.3 getpwent.3 getpwnam.3 \ - getpwent.3 getpwuid.3 getpwent.3 setpwent.3 getpwent.3 setpwfile.3 -MLINKS+=getpwent.3 getpwnam_r.3 getpwent.3 getpwuid_r.3 +MLINKS+=getpwent.3 endpwent.3 getpwent.3 setpassent.3 getpwent.3 setpwent.3 +MLINKS+=getpwnam.3 getpwuid.3 getpwnam.3 getpwnam_r.3 getpwnam.3 getpwuid_r.3 MLINKS+=getttyent.3 endttyent.3 getttyent.3 getttynam.3 getttyent.3 setttyent.3 MLINKS+=getusershell.3 endusershell.3 getusershell.3 setusershell.3 MLINKS+=glob.3 globfree.3 diff --git a/lib/libc/gen/getpwent.3 b/lib/libc/gen/getpwent.3 index bc5d092c23f..c0399f3215f 100644 --- a/lib/libc/gen/getpwent.3 +++ b/lib/libc/gen/getpwent.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: getpwent.3,v 1.23 2008/10/22 20:31:20 jmc Exp $ +.\" $OpenBSD: getpwent.3,v 1.24 2009/06/01 21:52:03 millert Exp $ .\" .\" Copyright (c) 1988, 1991, 1993 .\" The Regents of the University of California. All rights reserved. @@ -27,34 +27,19 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd $Mdocdate: October 22 2008 $ +.Dd $Mdocdate: June 1 2009 $ .Dt GETPWENT 3 .Os .Sh NAME .Nm getpwent , -.Nm getpwnam , -.Nm getpwuid , -.Nm getpwnam_r , -.Nm getpwuid_r , -.Nm setpassent , .Nm setpwent , .Nm endpwent -.Nd password database operations +.Nd sequential password database access .Sh SYNOPSIS .Fd #include <sys/types.h> .Fd #include <pwd.h> .Ft struct passwd * .Fn getpwent void -.Ft struct passwd * -.Fn getpwnam "const char *login" -.Ft struct passwd * -.Fn getpwuid "uid_t uid" -.Ft int -.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result" -.Ft int -.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result" -.Ft int -.Fn setpassent "int stayopen" .Ft void .Fn setpwent void .Ft void @@ -81,60 +66,38 @@ struct passwd { }; .Ed .Pp -The functions -.Fn getpwnam -and -.Fn getpwuid -search the password database for the given login name or user ID, -respectively, always returning the first one encountered. -.Pp -The re-entrant functions -.Fn getpwnam_r -and -.Fn getpwuid_r -search the password database for the given login name or user ID, -respectively, always returning the first one encountered. -The various strings associated with the result are stored in -.Va buf , -and -.Va pwstore -is updated to point at those strings. -.Pp +The .Fn getpwent -sequentially reads the password database and is intended for programs +function sequentially reads the password database and is intended for programs that wish to process the complete list of users. .Pp -.Fn setpassent -accomplishes two purposes. -First, it causes -.Fn getpwent -to -.Dq rewind -to the beginning of the database. -Additionally, if -.Fa stayopen -is non-zero, file descriptors are left open, significantly speeding -up subsequent accesses for all of the routines. -(This latter functionality is unnecessary for -.Fn getpwent -as it doesn't close its file descriptors by default.) -.Pp It is dangerous for long-running programs to keep the file descriptors open as the database will become out of date if it is updated while the program is running. +Furthermore, programs that run child processes should be careful to call +.Fn endpwent +to close these descriptors before calling +.Xr execve 2 +or +.Xr system 3 . .Pp .Fn setpwent -is equivalent to -.Fn setpassent -with an argument of zero. +causes +.Fn getpwent +to +.Dq rewind +to the beginning of the database. .Pp The .Fn endpwent -function closes any open files. +function closes any file descriptors opened by +.Fn setpwent +or +.Fn getpwent . .Pp These routines have been written to .Dq shadow -the password file, i.e., +the password file, that is, allow only certain programs to have access to the encrypted password. If the process which calls them has an effective UID of 0 or has the .Dq _shadow @@ -142,49 +105,22 @@ group in its group vector, the encrypted password will be returned, otherwise, the password field of the returned structure will point to the string .Ql * . .Sh YP SUPPORT -If YP is active, the functions -.Fn getpwent , -.Fn getpwnam , -and -.Fn getpwnam_r -also use the +If YP is active, +.Fn getpwent +also uses the .Pa master.passwd.byname YP map (if available) or the .Pa passwd.byname -YP map; and the functions -.Fn getpwuid -and -.Fn getpwuid_r -also use the -.Pa master.passwd.byuid -YP map (if available) or the -.Pa passwd.byuid YP map. This is in addition to the passwd file, and respects the order of both normal and YP entries in the passwd file. .Sh RETURN VALUES -The functions -.Fn getpwent , -.Fn getpwnam , -and -.Fn getpwuid -return a valid pointer to a passwd structure on success +The +.Fn getpwent +function returns a valid pointer to a passwd structure on success or a null pointer if end-of-file is reached or an error occurs. .Pp -The functions -.Fn getpwnam_r -and -.Fn getpwuid_r -update -.Va result -to point to -.Va pwstore -and then return 0 on success. -.Pp -The -.Fn setpassent -function returns 0 on failure or 1 on success. The .Fn endpwent and @@ -205,6 +141,7 @@ a Version 7 format password file .Xr getlogin 2 , .Xr getgrent 3 , .Xr getgrouplist 3 , +.Xr getpwnam 3 , .Xr pw_dup 3 , .Xr passwd 5 , .Xr Makefile.yp 8 , @@ -214,36 +151,31 @@ a Version 7 format password file .Sh HISTORY The .Fn getpwent , -.Fn getpwnam , -.Fn getpwuid , .Fn setpwent , and .Fn endpwent functions appeared in .At v7 . -The -.Fn setpassent -function appeared in -.Bx 4.3 Reno . .Pp The historic function .Xr setpwfile 3 , which allowed the specification of alternate password databases, has been deprecated and is no longer available. .Sh BUGS -The functions +The +.Fn getpwent +function stores its results in an internal static buffer and returns +a pointer to that buffer. +Subsequent calls to .Fn getpwent , .Fn getpwnam , -and +or .Fn getpwuid -leave their results in an internal static object and return -a pointer to that object. -Subsequent calls to any of these functions will modify the same object. +will overwrite the same buffer. .Pp The routines .Fn getpwent , .Fn endpwent , -.Fn setpassent , and .Fn setpwent are fairly useless in a networked environment and should be diff --git a/lib/libc/gen/getpwnam.3 b/lib/libc/gen/getpwnam.3 new file mode 100644 index 00000000000..f963ae3288a --- /dev/null +++ b/lib/libc/gen/getpwnam.3 @@ -0,0 +1,213 @@ +.\" $OpenBSD: getpwnam.3,v 1.1 2009/06/01 21:52:03 millert Exp $ +.\" +.\" Copyright (c) 1988, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd $Mdocdate: June 1 2009 $ +.Dt GETPWNAM 3 +.Os +.Sh NAME +.Nm getpwnam , +.Nm getpwuid , +.Nm getpwnam_r , +.Nm getpwuid_r , +.Nm setpassent +.Nd password database operations +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <pwd.h> +.Ft struct passwd * +.Fn getpwnam "const char *login" +.Ft struct passwd * +.Fn getpwuid "uid_t uid" +.Ft int +.Fn getpwnam_r "const char *login" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result" +.Ft int +.Fn getpwuid_r "uid_t uid" "struct passwd *pwstore" "char *buf" "size_t buflen" "struct passwd **result" +.Ft int +.Fn setpassent "int stayopen" +.Sh DESCRIPTION +These functions operate on the password database file which is described in +.Xr passwd 5 . +Each entry in the database is defined by the structure +.Li struct passwd +found in the include file +.Aq Pa pwd.h : +.Bd -literal -offset indent +struct passwd { + char *pw_name; /* user name */ + char *pw_passwd; /* encrypted password */ + uid_t pw_uid; /* user uid */ + gid_t pw_gid; /* user gid */ + time_t pw_change; /* password change time */ + char *pw_class; /* user access class */ + char *pw_gecos; /* Honeywell login info */ + char *pw_dir; /* home directory */ + char *pw_shell; /* default shell */ + time_t pw_expire; /* account expiration */ +}; +.Ed +.Pp +The functions +.Fn getpwnam +and +.Fn getpwuid +search the password database for the given login name or user ID, +respectively, always returning the first one encountered. +.Pp +The re-entrant versions, +.Fn getpwnam_r +and +.Fn getpwuid_r , +behave similarly but the various strings associated with the result +are stored in +.Va buf , +and +.Va pwstore +is updated to reference those strings. +.Pp +.Fn setpassent +accomplishes two purposes. +First, it causes +.Fn getpwent +to +.Dq rewind +to the beginning of the database. +Additionally, if +.Fa stayopen +is non-zero, file descriptors are left open, significantly speeding +up subsequent accesses for the lookup routines. +These file descriptors can be closed by a call to +.Fn endpwent . +.Pp +It is dangerous for long-running programs to keep the file descriptors +open as the database will become out of date if it is updated while the +program is running. +Furthermore, programs that run child processes should be careful to call +.Fn endpwent +to close these descriptors before calling +.Xr execve 2 +or +.Xr system 3 . +.Pp +These routines have been written to +.Dq shadow +the password file, that is, +allow only certain programs to have access to the encrypted password. +If the process which calls them has an effective UID of 0 or has the +.Dq _shadow +group in its group vector, the encrypted password will be returned, otherwise, +the password field of the returned structure will point to the string +.Ql * . +.Sh YP SUPPORT +If YP is active, the functions +.Fn getpwnam +and +.Fn getpwnam_r +also use the +.Pa master.passwd.byname +YP map (if available) or the +.Pa passwd.byname +YP map; and the functions +.Fn getpwuid +and +.Fn getpwuid_r +also use the +.Pa master.passwd.byuid +YP map (if available) or the +.Pa passwd.byuid +YP map. +This is in addition to the passwd file, +and respects the order of both normal and YP +entries in the passwd file. +.Sh RETURN VALUES +The functions +.Fn getpwnam +and +.Fn getpwuid +return a valid pointer to a passwd structure on success +or a null pointer if end-of-file is reached or an error occurs. +.Pp +The functions +.Fn getpwnam_r +and +.Fn getpwuid_r +update +.Va result +to point to +.Va pwstore +and then return 0 on success. +.Pp +The +.Fn setpassent +function returns 0 on failure or 1 on success. +.Sh FILES +.Bl -tag -width /etc/master.passwd -compact +.It Pa /etc/pwd.db +insecure password database file +.It Pa /etc/spwd.db +secure password database file +.It Pa /etc/master.passwd +current password file +.It Pa /etc/passwd +a Version 7 format password file +.El +.Sh SEE ALSO +.Xr getlogin 2 , +.Xr getgrent 3 , +.Xr getgrouplist 3 , +.Xr getpwent 3 , +.Xr pw_dup 3 , +.Xr passwd 5 , +.Xr Makefile.yp 8 , +.Xr pwd_mkdb 8 , +.Xr vipw 8 , +.Xr yp 8 +.Sh HISTORY +The +.Fn getpwnam +and +.Fn getpwuid +functions appeared in +.At v7 . +The +.Fn setpassent +function appeared in +.Bx 4.3 Reno . +.Sh BUGS +The +.Fn getpwnam +and +.Fn getpwuid +functions store their results in an internal static buffer and return +a pointer to that buffer. +Subsequent calls to +.Fn getpwent , +.Fn getpwnam , +or +.Fn getpwuid +will overwrite the same buffer. |