X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/91447636331957f3d9b5ca5b508f07c526b0074d..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/bsd/man/man2/setattrlist.2 diff --git a/bsd/man/man2/setattrlist.2 b/bsd/man/man2/setattrlist.2 index d2fbb6b53..4dcc7340d 100644 --- a/bsd/man/man2/setattrlist.2 +++ b/bsd/man/man2/setattrlist.2 @@ -20,26 +20,41 @@ .Dt SETATTRLIST 2 .Os Darwin .Sh NAME -.Nm setattrlist +.Nm setattrlist , +.Nm fsetattrlist , +.Nm setattrlistat .Nd set file system attributes .Sh SYNOPSIS .Fd #include .Fd #include .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. @@ -47,24 +62,104 @@ 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 -.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 @@ -81,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 . @@ -121,7 +219,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 +276,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 , @@ -252,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 . @@ -290,8 +427,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]; }; @@ -359,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. .