xnu-3789.70.16.tar.gz

[apple/xnu.git] / bsd / man / man2 / setattrlist.2

diff --git a/bsd/man/man2/setattrlist.2 b/bsd/man/man2/setattrlist.2
index d2fbb6b53e35a46659e4c02f982d7651f21bfdd9..68898eb3c747b804a552d95c1e6404cc77f7d4df 100644 (file)
--- a/bsd/man/man2/setattrlist.2
+++ b/bsd/man/man2/setattrlist.2
@@ -20,26 +20,38 @@
 .Dt SETATTRLIST 2
 .Os Darwin
 .Sh NAME
-.Nm setattrlist
+.Nm setattrlist ,
+.Nm fsetattrlist
 .Nd set file system attributes
 .Sh SYNOPSIS
 .Fd #include <sys/attr.h>
 .Fd #include <unistd.h>
 .Ft int
 .Fn setattrlist "const char* path" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
+.Ft int
+.Fn fsetattrlist "int fd" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "unsigned long options"
 .
 .Sh DESCRIPTION
 The
 .Fn setattrlist
-function sets attributes (that is, metadata) of file system objects.
-It is the logical opposite of 
+and
+.Fn fsetattrlist
+functions set attributes (that is, metadata) of file system objects.
+They are the logical opposite of
 .Xr getattrlist 2 .
-The function sets attributes about the file system object specified by 
+The 
+.Fn setattrlist
+function sets attributes about the file system object specified by 
 .Fa path
 from the values in the buffer specified by 
 .Fa attrBuf
 and
-.Fa attrBufSize .
+.Fa attrBufSize ;
+the
+.Fn fsetattrlist
+function does the same for the
+.Fa fd
+file descriptor.
 The 
 .Fa attrList 
 parameter determines what attributes are set. 
@@ -49,22 +61,79 @@ parameter lets you control specific aspects of the function's behaviour.
 .Pp
 .
 The 
-.Fn setattrlist 
-function is only supported by certain volume format implementations. 
+functions are only supported by certain volume format implementations. 
 For maximum compatibility, client programs should use high-level APIs 
 (such as the Carbon File Manager) to access file system attributes.
 These high-level APIs include logic to emulate file system attributes 
 on volumes that don't support 
-.Fn setattrlist .
+.Fn setattrlist
+and
+.Fn fsetattrlist .
 .Pp
 .
 .\" path parameter
 .
 The
 .Fa path
-parameter must reference a valid file system object.
+parameter for
+.Fn setattrlist
+must reference a valid file system object.
 All directories listed in the path name leading to the object 
 must be searchable.
+The
+.Fa fd
+parameter for
+.Fn fsetattrlist
+must be a valid file descriptor for the calling process.
+.
+The list of potentially settable attributes via 
+.Fn setattrlist
+is different than the list of attributes that are accessible via 
+.Fn getattrlist
+In particular, only the following attributes are modifiable via 
+.Fn setattrlist
+and not all of them may be supported on all filesystems.
+.Pp
+.
+.Bl -item -compact
+.It
+ATTR_CMN_SCRIPT
+.It 
+ATTR_CMN_CRTIME
+.It
+ATTR_CMN_MODTIME
+.It
+ATTR_CMN_CHGTIME
+.It
+ATTR_CMN_ACCTIME
+.It
+ATTR_CMN_BKUPTIME
+.It
+ATTR_CMN_FNDRINFO
+.It
+ATTR_CMN_OWNERID
+.It
+ATTR_CMN_GRPID
+.It
+ATTR_CMN_ACCESSMASK
+.It
+ATTR_CMN_FLAGS
+.It
+ATTR_CMN_EXTENDED_SECURITY
+.It
+ATTR_CMN_GRPUUID
+.Pp
+.It
+ATTR_VOL_NAME
+.It
+ATTR_VOL_INFO
+.Pp
+.It
+ATTR_FILE_DEVTYPE
+.El
+.Pp
+.
+.
 You must own the file system object in order to set any of the 
 following attributes: 
 .Pp
@@ -81,15 +150,16 @@ ATTR_CMN_CRTIME
 .It
 ATTR_CMN_MODTIME
 .It
-ATTR_CMN_CHGTIME
-.It
 ATTR_CMN_ACCTIME
+.Pp
+ATTR_CMN_CHGTIME 
+.Fa cannot be set programmatically. Any attempt to set change time is ignored.
 .El
 .Pp
 .
 You must be root (that is, your process's effective UID must be 0) in order to change the 
 .Dv ATTR_CMN_OWNERID
-attribute.
+attribute
 Setting other attributes requires that you have write access to the object.
 .Pp
 .
@@ -121,7 +191,7 @@ parameters specify a buffer that contains the attribute values to set.
 Attributes are packed in exactly the same way as they are returned from 
 .Xr getattrlist 2 
 except that, when setting attributes, the buffer does not include the leading 
-.Vt unsigned long 
+.Vt u_int32_t
 length value.
 .Pp
 .
@@ -178,34 +248,48 @@ you should be careful to support the behaviour specified by this document.
 .
 .Sh ERRORS
 .Fn setattrlist
+and
+.Fn fsetattrlist
 will fail if:
 .Bl -tag -width Er
 .
 .It Bq Er ENOTSUP
-The volume does not support
-.Fn setattrlist .
+The call is not supported by the volume.
 .
 .It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
+A component of the path for
+.Fn setattrlist
+prefix is not a directory.
 .
 .It Bq Er ENAMETOOLONG
-A component of a path name exceeded 
+A component of a path name for
+.Fn setattrlist
+exceeded 
 .Dv NAME_MAX
 characters, or an entire path name exceeded 
 .Dv PATH_MAX
 characters.
 .
 .It Bq Er ENOENT
-The file system object does not exist.
+The file system object for
+.Fn setattrlist
+does not exist.
+.
+.It Bq Er EBADF
+The file descriptor argument for
+.Fn fsetattrlist
+is not a valid file descriptor.
 .
 .It Bq Er EROFS
 The volume is read-only.
 .
 .It Bq Er EACCES
-Search permission is denied for a component of the path prefix.
+Search permission is denied for a component of the path prefix for
+.Fn setattrlist .
 .
 .It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
+Too many symbolic links were encountered in translating the pathname for
+.Fn setattrlist .
 .
 .It Bq Er EFAULT
 .Fa path ,
@@ -290,8 +374,8 @@ This assumes that the target volume supports the required attributes
 typedef struct attrlist attrlist_t;
 .Pp
 .
-struct FInfoAttrBuf 
-    unsigned long   length;
+struct FInfoAttrBuf {
+    u_int32_t       length;
     fsobj_type_t    objType;
     char            finderInfo[32];
 };