Return to getpwent.3 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / gen

Annotation of 43BSDReno/lib/libc/gen/getpwent.3, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1988 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted provided
        !             5: .\" that: (1) source distributions retain this entire copyright notice and
        !             6: .\" comment, and (2) distributions including binaries display the following
        !             7: .\" acknowledgement:  ``This product includes software developed by the
        !             8: .\" University of California, Berkeley and its contributors'' in the
        !             9: .\" documentation or other materials provided with the distribution and in
        !            10: .\" all advertising materials mentioning features or use of this software.
        !            11: .\" Neither the name of the University nor the names of its contributors may
        !            12: .\" be used to endorse or promote products derived from this software without
        !            13: .\" specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
        !            15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
        !            16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"    @(#)getpwent.3  6.6 (Berkeley) 6/23/90
        !            19: .\"
        !            20: .TH GETPWENT 3  "June 23, 1990"
        !            21: .AT 3
        !            22: .SH NAME
        !            23: getpwent, getpwnam, getpwuid, setpassent,
        !            24: setpwfile, setpwent, endpwent \- get password file entries
        !            25: .SH SYNOPSIS
        !            26: .nf
        !            27: .B #include <sys/types.h>
        !            28: .B #include <pwd.h>
        !            29: .PP
        !            30: .B struct passwd *getpwent()
        !            31: .PP
        !            32: .B struct passwd *getpwnam(login)
        !            33: .B char *login;
        !            34: .PP
        !            35: .B struct passwd *getpwuid(uid)
        !            36: .B uid_t uid;
        !            37: .PP
        !            38: .B int setpassent(stayopen)
        !            39: .B int stayopen;
        !            40: .PP
        !            41: .B void setpwfile(file)
        !            42: .B char *file;
        !            43: .PP
        !            44: .B int setpwent()
        !            45: .PP
        !            46: .B void endpwent()
        !            47: .fi
        !            48: .SH DESCRIPTION
        !            49: .IR Getpwent ,
        !            50: .IR getpwuid ,
        !            51: and
        !            52: .I getpwnam
        !            53: each return a pointer to a structure containing the broken-out
        !            54: fields of a line in the password file.  This structure is defined
        !            55: by the include file
        !            56: .IR < pwd.h > ,
        !            57: and contains the following fields:
        !            58: .PP
        !            59: .RS
        !            60: .nf
        !            61: struct passwd {
        !            62:        char    *pw_name;                       /* user name */
        !            63:        char    *pw_passwd;             /* encrypted password */
        !            64:        uid_t   pw_uid;         /* user uid */
        !            65:        gid_t   pw_gid;         /* user gid */
        !            66:        time_t  pw_change;      /* password change time */
        !            67:        char    *pw_class;              /* user access class */
        !            68:        char    *pw_gecos;              /* Honeywell login info */
        !            69:        char    *pw_dir;                        /* home directory */
        !            70:        char    *pw_shell;              /* default shell */
        !            71:        time_t  pw_expire;      /* account expiration */
        !            72: };
        !            73: .fi
        !            74: .RE
        !            75: .PP
        !            76: These fields are more completely described in
        !            77: .IR passwd (5).
        !            78: .PP
        !            79: .I Getpwnam
        !            80: and
        !            81: .I getpwuid
        !            82: search the password database for a matching user name or user uid,
        !            83: respectively, returning the first one encountered.  Identical
        !            84: user names or user uids may result in undefined behavior.
        !            85: .PP
        !            86: .I Getpwent
        !            87: sequentially reads the password database and is intended for programs
        !            88: that wish to step through the complete list of users.
        !            89: .PP
        !            90: All three routines will open the password file for reading, if
        !            91: necessary.
        !            92: .PP
        !            93: .I Setpwfile
        !            94: changes the default password file to
        !            95: .IR file ,
        !            96: thus allowing the use of alternate password files.
        !            97: .PP
        !            98: .I Setpassent
        !            99: opens the file or rewinds it if it is already open.  If
        !           100: .I stayopen
        !           101: is non-zero, file descriptors are left open, significantly speeding
        !           102: up subsequent calls.  This functionality is unnecessary for
        !           103: .I getpwent
        !           104: as it doesn't close its file descriptors by default.  It should also
        !           105: be noted that it is dangerous for long-running programs to use this
        !           106: functionality as the password file may be updated by
        !           107: .IR chpass (1),
        !           108: .IR passwd (1),
        !           109: or
        !           110: .IR vipw (8).
        !           111: .PP
        !           112: .I Setpwent
        !           113: is identical to
        !           114: .I setpassent
        !           115: with an argument of zero.
        !           116: .PP
        !           117: .I Endpwent
        !           118: closes any open files.
        !           119: .PP
        !           120: These routines have been written to ``shadow'' the password file, e.g.
        !           121: allow only certain programs to have access to the encrypted password.
        !           122: This is done by using the
        !           123: .IR mkpasswd (8)
        !           124: program, which creates
        !           125: .IR ndbm (3)
        !           126: databases that correspond to the password file, with the single exception
        !           127: that, rather than storing the encrypted password in the database, it stores
        !           128: the offset in the password file where the encrypted password may be found.
        !           129: .IR Getpwent ,
        !           130: .IR getpwnam ,
        !           131: and
        !           132: .I getpwuid
        !           133: will use the
        !           134: .I ndbm
        !           135: files in preference to the ``real'' password files, only reading the
        !           136: password file itself, to obtain the encrypted password, if the process
        !           137: is running with an effective user id equivalent to super-user.
        !           138: If the password file itself is protected, and the
        !           139: .I ndbm
        !           140: files are not, this makes the password available only to programs
        !           141: running with super-user privileges.
        !           142: .SH FILES
        !           143: /etc/passwd
        !           144: .SH "SEE ALSO"
        !           145: getlogin(3), getgrent(3), ndbm(3), passwd(5)
        !           146: .SH DIAGNOSTICS
        !           147: The routines
        !           148: .IR getpwent ,
        !           149: .IR getpwnam ,
        !           150: and
        !           151: .IR getpwuid ,
        !           152: return a null pointer on EOF or error.
        !           153: .I Setpassent
        !           154: and
        !           155: .I setpwent
        !           156: return 0 on failure and 1 on success.
        !           157: .I Endpwent
        !           158: and
        !           159: .I setpwfile
        !           160: have no return value.
        !           161: .SH BUGS
        !           162: All information is contained in a static buffer which is overwritten
        !           163: by each new call.  It must be copied elsewhere to be retained.
        !           164: .PP
        !           165: Intermixing calls to
        !           166: .IR getpwent
        !           167: with calls to
        !           168: .I getpwnam
        !           169: or
        !           170: .IR getpwuid ,
        !           171: or intermixing calls to
        !           172: .I getpwnam
        !           173: and
        !           174: .IR getpwuid ,
        !           175: after using
        !           176: .I setpassent
        !           177: to require that file descriptors be left open, may result
        !           178: in undefined behavior.
        !           179: .PP
        !           180: The routines
        !           181: .IR getpwent ,
        !           182: .IR endpwent ,
        !           183: .IR setpassent ,
        !           184: and
        !           185: .IR setpwent
        !           186: are fairly useless in a networked environment and should be
        !           187: avoided, if possible.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.