SETATTRLIST(2) BSD System Calls Manual SETATTRLIST(2)

NAME
     sseettaattttrrlliisstt - set file system attributes

SYNOPSIS
     ##iinncclluuddee <>
     ##iinncclluuddee <>

     int
     sseettaattttrrlliisstt(const char* path, struct attrlist * attrList, void * attrBuf,
         sizet attrBufSize, unsigned long options);

DESCRIPTION
     The sseettaattttrrlliisstt() function sets attributes (that is, metadata) of file
     system objects.  It is the logical opposite of getattrlist(2).  The func-
     tion sets attributes about the file system object specified by path from
     the values in the buffer specified by attrBuf and attrBufSize.  The
     attrList parameter determines what attributes are set.  The options
     parameter lets you control specific aspects of the function's behaviour.

     The sseettaattttrrlliisstt() function is 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 sseettaattttrrlliisstt().

     The path parameter must reference a valid file system object.  All direc-
     tories listed in the path name leading to the object must be searchable.
     You must own the file system object in order to set any of the following
     attributes:

     ATTRCMNGRPID
     ATTRCMNACCESSMASK
     ATTRCMNFLAGS
     ATTRCMNCRTIME
     ATTRCMNMODTIME
     ATTRCMNCHGTIME
     ATTRCMNACCTIME

     You must be root (that is, your process's effective UID must be 0) in
     order to change the ATTRCMNOWNERID attribute.  Setting other attributes
     requires that you have write access to the object.

     The attrList parameter is a pointer to an attrlist structure.  You are
     responsible for filling out all fields of this structure before calling
     the function.  See the discussion of the getattrlist(2) function for a
     detailed description of this structure.  To set an attribute you must set
     the corresponding bit in the appropriate attrgroupt field of the
     attrlist structure.

     The attrBuf and 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 getattrlist(2) except that, when setting
     attributes, the buffer does not include the leading unsigned long length
     value.

     The options parameter is a bit set that controls the behaviour of
     sseettaattttrrlliisstt().  The following option bits are defined.

     FSOPTNOFOLLOW  If this bit is set, sseettaattttrrlliisstt() will not follow a sym-
                     link if it occurs as the last component of path.

RETURN VALUES
     Upon successful completion a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

CCOOMMPPAATTIIBBIILLIITTYY
     Not all volumes support sseettaattttrrlliisstt().  However, if a volume supports
     getattrlist(2), it must also support sseettaattttrrlliisstt().  See the documenta-
     tion for getattrlist(2) for details on how to tell whether a volume sup-
     ports it.

     The sseettaattttrrlliisstt() 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 be-
     haviour than what is described here.  Your program is expected to be tol-
     erant of this variant behaviour.

     If you're implementing a volume format that supports sseettaattttrrlliisstt(), you
     should be careful to support the behaviour specified by this document.

EERRRROORRSS
     sseettaattttrrlliisstt() will fail if:

     [ENOTSUP]          The volume does not support sseettaattttrrlliisstt().

     [ENOTDIR]          A component of the path prefix is not a directory.

     [ENAMETOOLONG]     A component of a path name exceeded NAMEMAX charac-
                        ters, or an entire path name exceeded PATHMAX charac-
                        ters.

     [ENOENT]           The file system object does not exist.

     [EROFS]            The volume is read-only.

     [EACCES]           Search permission is denied for a component of the
                        path prefix.

     [ELOOP]            Too many symbolic links were encountered in translat-
                        ing the pathname.

     [EFAULT]           path, attrList or attrBuf points to an invalid
                        address.

     [EINVAL]           The bitmapcount field of attrList is not
                        ATTRBITMAPCOUNT.

     [EINVAL]           You try to set an invalid attribute.

     [EINVAL]           You try to set an attribute that is read-only.

     [EINVAL]           You try to set volume attributes and directory or file
                        attributes at the same time.

     [EINVAL]           You try to set volume attributes but path does not
                        reference the root of the volume.

     [EPERM]            You try to set an attribute that can only be set by
                        the owner.

     [EACCES]           You try to set an attribute that's only settable if
                        you have write permission, and you do not have write
                        permission.

     [EINVAL]           The buffer size you specified in attrBufSize is too
                        small to hold all the attributes that you are trying
                        to set.

     [EIO]              An I/O error occurred while reading from or writing to
                        the file system.

CCAAVVEEAATTSS
     If you try to set any volume attributes, you must set ATTRVOLINFO in
     the volattr field, even though it consumes no data from the attribute
     buffer.

     For more caveats, see also the compatibility notes above.

EEXXAAMMPPLLEESS
     The following code shows how to set the file type and creator of a file
     by getting the ATTRCMNFNDRINFO attribute using getattrlist(2), modify-
     ing the appropriate fields of the 32-byte Finder information structure,
     and then setting the attribute back using sseettaattttrrlliisstt().  This assumes
     that the target volume supports the required attributes

     #include 
     #include 
     #include 
     #include 
     #include 
     #include 
     #include 
     #include 

     typedef struct attrlist attrlistt;

     struct FInfoAttrBuf
         unsigned long   length;
         fsobjtypet    objType;
         char            finderInfo[32];
     };
     typedef struct FInfoAttrBuf FInfoAttrBuf;

     static int FInfoDemo(
         const char *path,
         const char *type,
         const char *creator
     )
     {
         int             err;
         attrlistt      attrList;
         FInfoAttrBuf    attrBuf;

         assert( strlen(type)    == 4 );
         assert( strlen(creator) == 4 );

         memset(&attrList, 0, sizeof(attrList));
         attrList.bitmapcount = ATTRBITMAPCOUNT;
         attrList.commonattr  = ATTRCMNOBJTYPE | ATTRCMNFNDRINFO;

         err = getattrlist(path, &attrList, &attrBuf, sizeof(attrBuf), 0);
         if (err != 0) {
             err = errno;
         }

         if ( (err == 0) && (attrBuf.objType != VREG) ) {
             fprintf(stderr, "Not a standard file.\n");
             err = EINVAL;
         } else {
             memcpy( &attrBuf.finderInfo[0], type,    4 );
             memcpy( &attrBuf.finderInfo[4], creator, 4 );

             attrList.commonattr = ATTRCMNFNDRINFO;
             err = setattrlist(
                 path,
                 &attrList,
                 attrBuf.finderInfo,
                 sizeof(attrBuf.finderInfo),
                 0
             );
         }

         return err;
     }

SEE ALSO
     chflags(2), chmod(2), chown(2), getattrlist(2), getdirentriesattr(2),
     searchfs(2), utimes(2)

HISTORY     A sseettaattttrrlliisstt() function call appeared in Darwin 1.3.1 (Mac OS X version
     10.0).

Darwin                         December 15, 2003                        Darwin