xnu-6153.11.26.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 c0e393ee64a78152babc3175e87f91c8a633dbe6..4dcc7340d131bf4b58df25731905380e5651da3f 100644 (file)
--- a/bsd/man/man2/setattrlist.2
+++ b/bsd/man/man2/setattrlist.2
@@ -21,15 +21,18 @@
 .Os Darwin
 .Sh NAME
 .Nm setattrlist ,
-.Nm fsetattrlist
+.Nm fsetattrlist ,
+.Nm setattrlistat
 .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"
+.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"
+.Ft int
+.Fn setattrlistat "int dir_fd" "const char * path" "struct attrlist * attrList" "void * attrBuf" "size_t attrBufSize" "uint32_t options"
 .
 .Sh DESCRIPTION
 The
@@ -59,6 +62,27 @@ The
 .Fa options 
 parameter lets you control specific aspects of the function's behaviour.
 .Pp
+The
+.Fn setattrlistat
+system call is equivalent to
+.Fn setattrlist
+except in the case where
+.Fa path
+specifies a relative path.
+In this case the attributes are set for the file system object named by
+path relative to the directory associated with the file descriptor
+.Fa fd
+instead of the current working directory.
+If
+.Fn setattrlistat
+is passed the special value
+.Dv AT_FDCWD
+in the
+.Fa fd
+parameter, the current working directory is used and the behavior is
+identical to a call to
+.Fn setattrlist .
+.Pp
 .
 The 
 functions are only supported by certain volume format implementations. 
@@ -85,6 +109,57 @@ The
 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
+.It
+ATTR_CMN_ADDEDTIME
+.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
@@ -101,15 +176,18 @@ ATTR_CMN_CRTIME
 .It
 ATTR_CMN_MODTIME
 .It
-ATTR_CMN_CHGTIME
-.It
 ATTR_CMN_ACCTIME
+.It
+ATTR_CMN_ADDEDTIME
+.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
 .
@@ -286,6 +364,31 @@ is too small to hold all the attributes that you are trying to set.
 An I/O error occurred while reading from or writing to the file system.
 .El
 .Pp
+.Pp
+In addition to the errors returned by the
+.Fn setattrlist ,
+the
+.Fn setattrlistat
+function may fail if:
+.Bl -tag -width Er
+.It Bq Er EBADF
+The
+.Fa path
+argument does not specify an absolute path and the
+.Fa fd
+argument is neither
+.Dv AT_FDCWD
+nor a valid file descriptor open for searching.
+.It Bq Er ENOTDIR
+The
+.Fa path
+argument is not an absolute path and
+.Fa fd
+is neither
+.Dv AT_FDCWD
+nor a file descriptor associated with a directory.
+.El
+.Pp
 .
 .Sh CAVEATS
 .
@@ -393,5 +496,6 @@ static int FInfoDemo(
 .Sh HISTORY
 A
 .Fn setattrlist
-function call appeared in Darwin 1.3.1 (Mac OS X version 10.0).
+function call appeared in Darwin 1.3.1 (Mac OS X version 10.0). The setatrlistat function call first
+appeared in macOS version 10.13.
 .