.Dt SETATTRLIST 2
.Os Darwin
.Sh NAME
-.Nm setattrlist
+.Nm setattrlist ,
+.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
.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.
.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
-.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
+.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
.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
.
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
.
.
.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 ,
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
.
typedef struct attrlist attrlist_t;
.Pp
.
-struct FInfoAttrBuf
- unsigned long length;
+struct FInfoAttrBuf {
+ u_int32_t length;
fsobj_type_t objType;
char finderInfo[32];
};
.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.
.
projects / apple / xnu.git / blobdiff