Libinfo-517.30.1.tar.gz

[apple/libinfo.git] / membership.subproj / mbr_uid_to_uuid.3

diff --git a/membership.subproj/mbr_uid_to_uuid.3 b/membership.subproj/mbr_uid_to_uuid.3
index 2e7aeec73ea34dc898514fe2e543dfef937cacc3..7529d7e60f89f5f45ebe2e658e2e57496b73bd03 100644 (file)
--- a/membership.subproj/mbr_uid_to_uuid.3
+++ b/membership.subproj/mbr_uid_to_uuid.3
@@ -1,4 +1,4 @@
-.\" Copyright (c) 2005-2007 Apple Inc
+.\" Copyright (c) 2005-2010 Apple Inc
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -26,7 +26,7 @@
 .\" SUCH DAMAGE.
 .\"
 .\"
-.Dd February 3, 2005
+.Dd October 10, 2011
 .Dt MBR_UID_TO_UUID 3
 .Os "Mac OS X"
 .Sh NAME
@@ -48,6 +48,10 @@
 .Fn mbr_sid_to_uuid "const nt_sid_t *sid" "uuid_t uu"
 .Ft int
 .Fn mbr_uuid_to_sid "const uuid_t uu" "nt_sid_t *sid"
+.Ft int
+.Fn mbr_sid_to_string "const nt_sid_t *sid" "char *string"
+.Ft int
+.Fn mbr_string_to_sid "const char *string" "nt_sid_t *sid"
 .Sh DESCRIPTION
 Users and groups can be referred to in multiple ways.
 In addition to the traditional uid and gid, 
@@ -55,16 +59,21 @@ every user or group can be referenced by a 128 bit uuid.
 Additionally, if the user or group is hosted on a PDC
 or Active Directory server, it will have a 128 bit or larger sid.
 .Pp
-These routines communicate with the
-.Xr DirectoryService 8
-daemon.
+These routines communicate with
+.Xr opendirectoryd 8 .
 .Pp
 .Fn mbr_uid_to_uuid
 takes a uid and looks up the associated user account.
 It provides the the uuid for that user as an output parameter.
+Note that this routine will succeed and return a fabricated uuid if the input user uid does not exist.
+.Fn getpwuid
+should be used to test for the existence of a uid.
 .Pp
 .Fn mbr_gid_to_uuid
 similarly gets the uuid associated with a group.
+Note that this routine will succeed and return a fabricated uuid if the input group gid does not exist.
+.Fn getgrgid
+should be used to test for the existence of a gid.
 .Pp
 .Fn mbr_uuid_to_id
 takes a uuid that refers to a user or group and fetches the corresponding uid or gid.
@@ -73,7 +82,7 @@ is set to ID_TYPE_UID or ID_TYPE_GID to indicate which type was found.
 Note that
 .Fn mbr_uuid_to_id
 always returns an id even if the uuid is not found.
-This returned id is not persistant, 
+This returned id is not persistent,
 but can be used to map back to the uuid during runtime.
 To determine if the uuid exists, the returned id can be used in a call to
 .Xr getpwuid 3
@@ -82,20 +91,47 @@ or
 .Pp
 .Fn mbr_sid_to_uuid
 takes a sid and returns the associated uuid.
-Like
-.Fn mbr_uuid_to_id ,
-.Fn mbr_sid_to_uuid
-always returns a uuid for the sid, even if the sid can not be found.
 .Pp
 .Fn mbr_uuid_to_sid
 returns a sid for the associated uuid.
+.Pp
+Two additional utility functions are available to convert between sids and a string representation.
+String representations may be required, for example, when text files or XML files are used to save sid values.
+.Pp
+.Fn mbr_sid_to_string
+converts a sid into a string representation.
+The 
+.Fa string
+parameter must be a buffer of at least 194 characters.
+The converted string is terminated with a nul character.
+.Pp
+.Fn mbr_string_to_sid
+converts an external string representation into a sid.
 .Sh RETURN VALUES
-These functions return 0 on success, or EIO if communications with the
-.Xr DirectoryService 8
-daemon fails.
-ENOENT is returned if the mapping can not be performed.
+These functions return 0 on success or one of the following error codes on failure:
+.Bl -tag -width Er
+.It Bq Er EIO
+Communication with
+.Xr opendirectoryd 8
+failed.
+.It Bq Er ENOENT
+The mapping can not be performed.
+.It Bq Er EAUTH
+Communication with
+.Xr opendirectoryd 8
+failed due to an authentication error.
+.It Bq Er EINVAL
+Invalid arguments were provided.
+.It Bq Er ENOMEM
+Insufficient storage space is available.
+.El
+.Pp
+.Fn mbr_gid_to_uuid
+and
+.Fn mbr_uid_to_uuid
+return 0 (success), even if the user/group does not exist.
 .Sh SEE ALSO
 .Xr getpwuid 3 ,
 .Xr getgrgid 3 ,
 .Xr mbr_check_membership 3 ,
-.Xr DirectoryService 8
\ No newline at end of file
+.Xr opendirectoryd 8