.\" Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
.\" 
.\" The contents of this file constitute Original Code as defined in and
.\" are subject to the Apple Public Source License Version 1.1 (the
.\" "License").  You may not use this file except in compliance with the
.\" License.  Please obtain a copy of the License at
.\" http://www.apple.com/publicsource and read it before using this file.
.\" 
.\" This Original Code and all software distributed under the License are
.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
.\" License for the specific language governing rights and limitations
.\" under the License.
.\" 
.\"     @(#)setattrlist.2
.
.Dd December 15, 2003
.Dt SETATTRLIST 2
.Os Darwin
.Sh NAME
.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"
.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
and
.Fn fsetattrlist
functions set attributes (that is, metadata) of file system objects.
They are the logical opposite of
.Xr getattrlist 2 .
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 ;
the
.Fn fsetattrlist
function does the same for the
.Fa fd
file descriptor.
The 
.Fa attrList 
parameter determines what attributes are set. 
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. 
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
and
.Fn fsetattrlist .
.Pp
.
.\" path parameter
.
The
.Fa path
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
.
.Bl -item -compact
.It
ATTR_CMN_GRPID
.It
ATTR_CMN_ACCESSMASK
.It
ATTR_CMN_FLAGS
.It
ATTR_CMN_CRTIME
.It
ATTR_CMN_MODTIME
.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
.
.Pp
If ATTR_CMN_MODTIME is set to a time before ATTR_CMN_CRTIME, the value of
ATTR_CMN_CRTIME is set to the same value as ATTR_CMN_MODTIME.
.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
Setting other attributes requires that you have write access to the object.
.Pp
.
.\" attrList parameter
.
The
.Fa attrList
parameter is a pointer to an 
.Vt attrlist 
structure. 
You are responsible for filling out all fields of this structure before calling the function. 
See the discussion of the  
.Xr getattrlist 2 
function for a detailed description of this structure. 
To set an attribute you must set the corresponding bit in the appropriate 
.Vt attrgroup_t 
field of the 
.Vt attrlist 
structure.
.Pp
.
.\" attrBuf and attrBufSize parameters
.
The
.Fa attrBuf
and 
.Fa attrBufSize
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 u_int32_t
length value.
.Pp
.
.\" option parameter
.
The
.Fa options
parameter is a bit set that controls the behaviour of
.Fn setattrlist .
The following option bits are defined.
.
.Bl -tag -width FSOPT_RESOLVE_BENEATH
.
.It FSOPT_NOFOLLOW
If this bit is set, 
.Fn setattrlist 
will not follow a symlink if it occurs as 
the last component of
.Fa path .
.
.It FSOPT_NOFOLLOW_ANY
If this bit is set,
.Fn setattrlist
will not follow a symlink if it occurs as
the last component of
.Fa path .
In addition, if a symbolic link is encountered
before the final component, an error is
returned
.
.It FSOPT_RESOLVE_BENEATH
If this bit is set, path resolution must not escape the directory associated
with the file descriptor.
.
.It FSOPT_UNIQUE
If this bit is set, the path lookup will fail if the target file has multiple
hard links.
.
.El
.
.Sh RETURN VALUES
Upon successful completion a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Va errno
is set to indicate the error.
.
.Sh COMPATIBILITY
Not all volumes support 
.Fn setattrlist .
However, if a volume supports 
.Xr getattrlist 2 ,
it must also support 
.Fn setattrlist .
See the documentation for 
.Xr getattrlist 2 
for details on how to tell whether a volume supports it.
.Pp
.
The 
.Fn setattrlist 
function has been undocumented for more than two years. 
In that time a number of volume format implementations have been created without 
a proper specification for the behaviour of this routine. 
You may encounter volume format implementations with slightly different 
behaviour than what is described here. 
Your program is expected to be tolerant of this variant behaviour.
.Pp
.
If you're implementing a volume format that supports 
.Fn setattrlist ,
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 call is not supported by the volume.
.
.It Bq Er ENOTDIR
A component of the path for
.Fn setattrlist
prefix is not a directory.
.
.It Bq Er ENAMETOOLONG
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 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 for
.Fn setattrlist .
.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname for
.Fn setattrlist .
.
.It Bq Er ELOOP
FSOPT_NOFOLLOW_ANY was passed and a symbolic link was encountered in
translating the pathname for
.Fn setattrlist .
.
.It Bq Er EFAULT
.Fa path ,
.Fa attrList
or
.Em attrBuf
points to an invalid address.
.
.It Bq Er EINVAL
The 
.Fa bitmapcount 
field of 
.Fa attrList 
is not 
.Dv ATTR_BIT_MAP_COUNT .
.
.It Bq Er EINVAL
You try to set an invalid attribute.
.
.It Bq Er EINVAL
You try to set an attribute that is read-only.
.
.It Bq Er EINVAL
You try to set volume attributes and directory or file attributes at the same time.
.
.It Bq Er EINVAL
You try to set volume attributes but 
.Fa path 
does not reference the root of the volume.
.
.It Bq Er EPERM
You try to set an attribute that can only be set by the owner.
.
.It Bq Er EACCES
You try to set an attribute that's only settable if you have write permission, 
and you do not have write permission.
.
.It Bq Er EINVAL
The buffer size you specified in 
.Fa attrBufSize 
is too small to hold all the attributes that you are trying to set.
.
.It Bq Er EIO
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.
.It Bq Er ENOTCAPABLE
if FSOPT_RESOLVE_BENEATH was passed and
.Fa path
does not reside in the directory hierarchy beneath the starting directory.
.It Bq Er ENOTCAPABLE
if FSOPT_UNIQUE was passed and
.Fa path
has multiple hard links.
.El
.Pp
.
.Sh CAVEATS
.
If you try to set any volume attributes, you must set 
.Dv ATTR_VOL_INFO 
in the 
.Fa volattr
field, even though it consumes no data from the attribute buffer.
.Pp
.
For more caveats, see also the compatibility notes above.
.
.Sh EXAMPLES
.
The following code shows how to set the file type and creator of 
a file by getting the 
.Dv ATTR_CMN_FNDRINFO 
attribute using 
.Xr getattrlist 2 , 
modifying the appropriate fields of the 32-byte Finder information structure, 
and then setting the attribute back using 
.Fn setattrlist . 
This assumes that the target volume supports the required attributes
.
.Bd -literal
#include <assert.h>
#include <stdio.h>
#include <stddef.h>
#include <string.h>
#include <sys/attr.h>
#include <sys/errno.h>
#include <unistd.h>
#include <sys/vnode.h>
.Pp
.
typedef struct attrlist attrlist_t;
.Pp
.
struct FInfoAttrBuf {
    u_int32_t       length;
    fsobj_type_t    objType;
    char            finderInfo[32];
};
typedef struct FInfoAttrBuf FInfoAttrBuf;
.Pp
.
static int FInfoDemo(
    const char *path, 
    const char *type, 
    const char *creator
)
{
    int             err;
    attrlist_t      attrList;
    FInfoAttrBuf    attrBuf;
.Pp
    
    assert( strlen(type)    == 4 );
    assert( strlen(creator) == 4 );
.Pp
.
    memset(&attrList, 0, sizeof(attrList));
    attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
    attrList.commonattr  = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
.Pp
    
    err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
    if (err != 0) {
        err = errno;
    }
.Pp
    
    if ( (err == 0) && (attrBuf.objType != VREG) ) {
        fprintf(stderr, "Not a standard file.\en");
        err = EINVAL;
    } else {
        memcpy( &attrBuf.finderInfo[0], type,    4 );
        memcpy( &attrBuf.finderInfo[4], creator, 4 );
        
        attrList.commonattr = ATTR_CMN_FNDRINFO;
        err = setattrlist(
            path, 
            &attrList, 
            attrBuf.finderInfo, 
            sizeof(attrBuf.finderInfo), 
            0
        );
    }
.Pp
    return err;
}
.Ed
.Pp
.
.Sh SEE ALSO
.
.Xr chflags 2 ,
.Xr chmod 2 ,
.Xr chown 2 ,
.Xr getattrlist 2 ,
.Xr getdirentriesattr 2 ,
.Xr searchfs 2 ,
.Xr utimes 2
.
.Sh HISTORY
A
.Fn setattrlist
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.
.