From 62ab31a2320799f21e7e9ac25349857cf975def9 Mon Sep 17 00:00:00 2001 From: Keith Bostic Date: Sat, 17 Sep 1988 19:49:52 -0800 Subject: [PATCH] rework get{gr,pw,fs}ent to all be about the same; fix some obvious problems, document that set{gr,pw,fs}ent closes any open files SCCS-vsn: lib/libc/gen/getgrent.3 6.3 SCCS-vsn: lib/libc/gen/getpwent.3 6.4 SCCS-vsn: lib/libc/gen/getfsent.3 6.6 --- usr/src/lib/libc/gen/getfsent.3 | 22 +++--- usr/src/lib/libc/gen/getgrent.3 | 117 +++++++++++++++----------------- usr/src/lib/libc/gen/getpwent.3 | 84 ++++++++++++----------- 3 files changed, 113 insertions(+), 110 deletions(-) diff --git a/usr/src/lib/libc/gen/getfsent.3 b/usr/src/lib/libc/gen/getfsent.3 index 5effbe1965..b4ca66eb0b 100644 --- a/usr/src/lib/libc/gen/getfsent.3 +++ b/usr/src/lib/libc/gen/getfsent.3 @@ -13,7 +13,7 @@ .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" -.\" @(#)getfsent.3 6.5 (Berkeley) %G% +.\" @(#)getfsent.3 6.6 (Berkeley) %G% .\" .TH GETFSENT 3 "" .UC 4 @@ -62,11 +62,9 @@ struct fstab { The fields have meanings described in .IR fstab (5). .PP -.I Getfsent -reads the next line of the file, opening the file if necessary. -.PP .I Setfsent -opens the file, or rewinds it if it is already open. +opens the file (closing any previously opened file) or rewinds it +if it is already open. .PP .I Endfsent closes the file. @@ -74,11 +72,15 @@ closes the file. .I Getfsspec and .I getfsfile -sequentially search from the beginning of the file until a matching -special file name or file system file name is found, or until EOF is -encountered. +search the entire file (opening it if necessary) for a matching special +file name or file system file name. +.PP +For programs wishing to read the entire database, +.I getfsent +reads the next entry (opening the file if necessary). .PP -Entries in the file with a type field equivalent to \fIFSTAB_XX\fP +All entries in the file with a type field equivalent to +.I FSTAB_XX are ignored. .SH FILES /etc/fstab @@ -91,7 +93,7 @@ and .I getfsfile return a null pointer (0) on EOF or error. .I Setfsent -returns 0 on success, 1 on failure. +returns 0 on failure, 1 on success. .I Endfsent returns nothing. .SH BUGS diff --git a/usr/src/lib/libc/gen/getgrent.3 b/usr/src/lib/libc/gen/getgrent.3 index 5af5b0a730..2e687e732c 100644 --- a/usr/src/lib/libc/gen/getgrent.3 +++ b/usr/src/lib/libc/gen/getgrent.3 @@ -1,4 +1,8 @@ -.\" @(#)getgrent.3 6.2 (Berkeley) %G% +.\" Copyright (c) 1988 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getgrent.3 6.3 (Berkeley) %G% .\" .TH GETGRENT 3 "" .AT 3 @@ -6,21 +10,22 @@ getgrent, getgrgid, getgrnam, setgrent, endgrent setgrfile \- get group file entry .SH SYNOPSIS .nf +.B #include .B #include .PP .B struct group *getgrent() .PP .B struct group *getgrgid(gid) -.B int gid; +.B gid_t gid; .PP .B struct group *getgrnam(name) .B char *name; .PP .B setgrent() .PP -.B endgrent() +.B void endgrent() .PP -.B setgrfile(name) +.B void setgrfile(name) .B char *name; .fi .SH DESCRIPTION @@ -28,79 +33,67 @@ getgrent, getgrgid, getgrnam, setgrent, endgrent setgrfile \- get group file ent .I getgrgid and .I getgrnam -each return pointers -to an object -with the following structure -containing the broken-out -fields of a line in the group file. +each return pointers to an object with the following structure +containing the broken-out fields of a line in the group file, +as described in +.IR < grp.h > . .RS .PP .nf -.so /usr/include/grp.h +struct group { + char *gr_name; + char *gr_passwd; + gid_t gr_gid; + char **gr_mem; +}; +.ft R +.ad .fi .RE .PP -The members of this structure are: -.TP \w'gr_passwd'u+2n -gr_name -The name of the group. -.br -.ns -.TP \w'gr_passwd'u+2n -gr_passwd -The encrypted password of the group. -.br -.ns -.TP \w'gr_passwd'u+2n -gr_gid -The numerical group-ID. -.br -.ns -.TP \w'gr_passwd'u+2n -gr_mem -Null-terminated vector -of pointers to the individual -member names. +The fields have meanings described in +.IR grp (5). .PP -.I Getgrent -simply reads the next -line while -.I getgrgid +.I Setgrfile +changes the default group file to +.IR name , +thus allowing usage of alternate group files. +.PP +.I Setgrent +opens the file (closing any previously opened file) or rewinds it +if it it already open. +.PP +.I Endgrent +closes any open files. +.PP +.I Getgrgid and .I getgrnam -search until a matching +search the entire file (opening it if necessary) for a matching .I gid or -.I name -is found -(or until EOF is encountered). -Each routine picks up -where the others leave off -so successive calls may be used -to search the entire file. +.IR name . .PP -A call to -.I setgrent -has the effect of rewinding -the group file -to allow -repeated searches. -.I Endgrent -may be called to -close the group file -when processing is complete. -.PP -\fISetgrfile\fP changes the default group file to \fIname\fP thus allowing -alternate grioup files to be used. Note that it does \fInot\fP close the -previous file. If this is desired, \fIendgrent\fP should be called prior -to it. +For programs wishing to read the entire database, +.I getgrent +reads the next entry (opening the file if necessary). .SH FILES /etc/group .SH "SEE ALSO" getlogin(3), getpwent(3), group(5) .SH DIAGNOSTICS -A null pointer -(0) is returned on EOF or error. +The routines +.IR getgrent , +.IR getgruid , +and +.IR getgrnam , +return a null pointer (0) on EOF or error. +.I Setgrent +returns 0 on failure, 1 on success. +.I Endgrent +and +.I setgrfile +have no return value. .SH BUGS -All information is contained in a static area so it must be copied if it is -to be saved. +All information is contained in a static area so it must be +copied if it is to be saved. diff --git a/usr/src/lib/libc/gen/getpwent.3 b/usr/src/lib/libc/gen/getpwent.3 index c38d887c07..68f696d8c0 100644 --- a/usr/src/lib/libc/gen/getpwent.3 +++ b/usr/src/lib/libc/gen/getpwent.3 @@ -1,4 +1,8 @@ -.\" @(#)getpwent.3 6.3 (Berkeley) %G% +.\" Copyright (c) 1988 Regents of the University of California. +.\" All rights reserved. The Berkeley software License Agreement +.\" specifies the terms and conditions for redistribution. +.\" +.\" @(#)getpwent.3 6.4 (Berkeley) %G% .\" .TH GETPWENT 3 "" .AT 3 @@ -9,16 +13,16 @@ getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file .B #include .PP .B struct passwd *getpwuid(uid) -.B int uid; +.B uid_t uid; .PP .B struct passwd *getpwnam(name) .B char *name; .PP .B struct passwd *getpwent() .PP -.B setpwent() +.B void setpwent() .PP -.B endpwent() +.B void endpwent() .PP .B setpwfile(name) .B char *name; @@ -28,14 +32,24 @@ getpwent, getpwuid, getpwnam, setpwent, endpwent, setpwfile \- get password file .I getpwuid and .I getpwnam -each return a pointer to an object with the -following structure -containing the broken-out -fields of a line in the password file. +each return a pointer to an object with the following structure, +containing the broken-out fields of a line in the password file, +as described in +.IR < pwd.h > . .RS .PP .nf -.so /usr/include/pwd.h +struct passwd { + char *pw_name; + char *pw_passwd; + uid_t pw_uid; + gid_t pw_gid; + int pw_quota; + char *pw_comment; + char *pw_gecos; + char *pw_dir; + char *pw_shell; +}; .ft R .ad .fi @@ -48,41 +62,31 @@ and are unused; the others have meanings described in .IR passwd (5). .PP -Searching of the password file is done using the \fIndbm\fP -database access routines. +.I Setpwfile +changes the default password file to +.IR name , +thus allowing usage of alternate password files. If \fIndbm\fP databases +are available for any password files, they are used, otherwise the file +itself is linearly searched. +.PP .I Setpwent -opens the database; -.I endpwent -closes it. +opens the database or file (closing any previously opened database or file) +or rewinds it if it is already open. +.PP +.I Endpwent +closes any open databases or files. +.PP .I Getpwuid and .I getpwnam -search the database (opening it if necessary) for a matching +search the entire database or file (opening it if necessary) for a matching .I uid or .IR name . -EOF is returned if there is no entry. .PP For programs wishing to read the entire database, .I getpwent -reads the next -line (opening the database if necessary). -In addition to opening the database, -.I setpwent -can be used to make -.I getpwent -begin its search from the beginning of the database. -.PP -.I Setpwfile -changes the default password file to -.I name -thus allowing alternate password files to be used. -Note that it does -.I not -close the previous file. -If this is desired, -.I endpwent -should be called prior to it. +reads the next entry (opening the database or file if necessary). .SH FILES /etc/passwd .SH "SEE ALSO" @@ -94,8 +98,12 @@ The routines and .IR getpwnam , return a null pointer (0) on EOF or error. +.I Setpwent +returns 0 on failure, 1 on success. +.I Endpwent +and +.I setpwfile +have no return value. .SH BUGS -All information -is contained in a static area -so it must be copied if it is -to be saved. +All information is contained in a static area so it must be +copied if it is to be saved. -- 2.20.1