Libc-391.4.3.tar.gz

[apple/libc.git] / gen / getpwent.3

diff --git a/gen/getpwent.3 b/gen/getpwent.3
index 6ce2003fb19d9fe9056ac8ecc605f05020c14d8d..9c7badf94cfa9e2bbc5c2ee427e11842ef25baf9 100644 (file)
--- a/gen/getpwent.3
+++ b/gen/getpwent.3
@@ -56,7 +56,7 @@
 .Fn getpwuid "uid_t uid"
 .Ft int
 .Fn setpassent "int  stayopen"
 .Fn getpwuid "uid_t uid"
 .Ft int
 .Fn setpassent "int  stayopen"

-.Ft void
+.Ft int

 .Fn setpwent void
 .Ft void
 .Fn endpwent void
 .Fn setpwent void
 .Ft void
 .Fn endpwent void


@@ -131,12 +131,41 @@ The
 function
 closes any open files.
 .Pp
 function
 closes any open files.
 .Pp

-These routines have been written to ``shadow'' the password file, e.g.\&
+As of Mac OS X 10.3, there are now different per-user behaviours of 
+this function, based on the AuthenticationAuthority value 
+stored for the queried user in DirectoryServices.
+.Pp
+If the queried user is still a legacy crypt password user or now 
+has an AuthenticationAuthority value containing ``;basic;'',
+these routines will behave in their standard BSD fashion.
+These functions will ``shadow'' the password file, e.g.\&

 allow only certain programs to have access to the encrypted password.
 If the process which calls them has an effective uid of 0, the encrypted
 password will be returned, otherwise, the password field of the returned
 structure will point to the string
 .Ql * .
 allow only certain programs to have access to the encrypted password.
 If the process which calls them has an effective uid of 0, the encrypted
 password will be returned, otherwise, the password field of the returned
 structure will point to the string
 .Ql * .

+.Pp
+By default in Mac OS X 10.3 and later all users will have an 
+AuthenticationAuthority with the value ``;ShadowHash;''.
+These users will have a visible password value of ``********''.
+These functions
+will have no access to the encrypted password whatsoever.
+Setting or changing 
+an user password must be done entirely through the DirectoryService APIs 
+for this default user.
+.Pp
+There also exists an ``Apple Password Server'' user whose password 
+value is also ``********'' and with an AuthenticationAuthority that 
+contains the value ";ApplePasswordServer;" among other data.
+There is no getpwnam access to the password for this user either 
+and again set/change password can be done through the DirectoryService API.
+.Pp
+Finally in support of local user caching there is a local cached user 
+whose password is also ``********'' and has an AuthenticationAuthority 
+value containing ``;LocalCachedUser;'' among other data.
+These functions also provide no access to the password for this user 
+and set/change password functionality is through the DirectoryService API.
+.Pp

 .Sh RETURN VALUES
 The functions
 .Fn getpwent ,
 .Sh RETURN VALUES
 The functions
 .Fn getpwent ,


@@ -147,13 +176,13 @@ return a valid pointer to a passwd structure on success
 and a null pointer if end-of-file is reached or an error occurs.
 The
 .Fn setpassent
 and a null pointer if end-of-file is reached or an error occurs.
 The
 .Fn setpassent

-function returns 0 on failure and 1 on success.
+and 
+.Fn setpwent
+functions return 0 on failure and 1 on success.

 The
 .Fn endpwent
 The
 .Fn endpwent

-and
-.Fn setpwent
-functions
-have no return value.
+function
+has no return value.

 .Sh FILES
 .Bl -tag -width /etc/master.passwd -compact
 .It Pa /etc/pwd.db
 .Sh FILES
 .Bl -tag -width /etc/master.passwd -compact
 .It Pa /etc/pwd.db


@@ -169,7 +198,6 @@ A Version 7 format password file
 .Xr getlogin 2 ,
 .Xr getgrent 3 ,
 .Xr yp 4 ,
 .Xr getlogin 2 ,
 .Xr getgrent 3 ,
 .Xr yp 4 ,

-.Xr nsswitch.conf 5 ,

 .Xr passwd 5 ,
 .Xr pwd_mkdb 8 ,
 .Xr vipw 8
 .Xr passwd 5 ,
 .Xr pwd_mkdb 8 ,
 .Xr vipw 8


@@ -212,7 +240,3 @@ and
 .Fn setpwent
 are fairly useless in a networked environment and should be
 avoided, if possible.
 .Fn setpwent
 are fairly useless in a networked environment and should be
 avoided, if possible.

-.Fn getpwent
-makes no attempt to suppress duplicate information if multiple
-sources are specified in
-.Xr nsswitch.conf 5 .