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
 .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"
 .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
 .
 .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 .
 .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 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. 
 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 
 .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 
 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
 .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.
 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
 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
 .It
 ATTR_CMN_MODTIME
 .It

-ATTR_CMN_CHGTIME
-.It

 ATTR_CMN_ACCTIME
 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
 .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
 .
 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 
 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
 .
 length value.
 .Pp
 .


@@ -178,34 +248,48 @@ you should be careful to support the behaviour specified by this document.
 .
 .Sh ERRORS
 .Fn setattrlist
 .
 .Sh ERRORS
 .Fn setattrlist

+and
+.Fn fsetattrlist

 will fail if:
 .Bl -tag -width Er
 .
 .It Bq Er ENOTSUP
 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
 .
 .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
 .
 .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
 .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
 .
 .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
 .
 .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 ,
 .
 .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
 .
 typedef struct attrlist attrlist_t;
 .Pp
 .

-struct FInfoAttrBuf 
-    unsigned long   length;
+struct FInfoAttrBuf {
+    u_int32_t       length;

     fsobj_type_t    objType;
     char            finderInfo[32];
 };
     fsobj_type_t    objType;
     char            finderInfo[32];
 };