|
ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages
|
|
This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles. For more information about the manual page format, see the manual page for manpages(5). |
SETATTRLIST(2) BSD System Calls Manual SETATTRLIST(2)
NAME
setattrlist -- set file system attributes
SYNOPSIS
#include <sys/attr.h>
#include <unistd.h>
int
setattrlist(const char* path, struct attrlist * attrList, void * attrBuf,
size_t attrBufSize, unsigned long options);
DESCRIPTION
The setattrlist() function sets attributes (that is, metadata) of file
system objects. It is the logical opposite of getattrlist(2). The func-tion function
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 setattrlist() 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 setattrlist().
The path parameter must reference a valid file system object. All direc-tories directories
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:
ATTR_CMN_GRPID
ATTR_CMN_ACCESSMASK
ATTR_CMN_FLAGS
ATTR_CMN_CRTIME
ATTR_CMN_MODTIME
ATTR_CMN_CHGTIME
ATTR_CMN_ACCTIME
You must be root (that is, your process's effective UID must be 0) in
order to change the ATTR_CMN_OWNERID 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 attrgroup_t 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
setattrlist(). The following option bits are defined.
FSOPT_NOFOLLOW If this bit is set, setattrlist() will not follow a sym-link symlink
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.
COMPATIBILITY
Not all volumes support setattrlist(). However, if a volume supports
getattrlist(2), it must also support setattrlist(). See the documenta-tion documentation
tion for getattrlist(2) for details on how to tell whether a volume sup-ports supports
ports it.
The 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 be-haviour behaviour
haviour than what is described here. Your program is expected to be tol-erant tolerant
erant of this variant behaviour.
If you're implementing a volume format that supports setattrlist(), you
should be careful to support the behaviour specified by this document.
ERRORS
setattrlist() will fail if:
[ENOTSUP] The volume does not support setattrlist().
[ENOTDIR] A component of the path prefix is not a directory.
[ENAMETOOLONG] A component of a path name exceeded NAME_MAX charac-ters, characters,
ters, or an entire path name exceeded PATH_MAX charac-ters. characters.
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 translating
ing the pathname.
[EFAULT] path, attrList or attrBuf points to an invalid
address.
[EINVAL] The bitmapcount field of attrList is not
ATTR_BIT_MAP_COUNT.
[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.
CAVEATS
If you try to set any volume attributes, you must set ATTR_VOL_INFO in
the volattr field, even though it consumes no data from the attribute
buffer.
For more caveats, see also the compatibility notes above.
EXAMPLES
The following code shows how to set the file type and creator of a file
by getting the ATTR_CMN_FNDRINFO attribute using getattrlist(2), modify-ing modifying
ing the appropriate fields of the 32-byte Finder information structure,
and then setting the attribute back using setattrlist(). This assumes
that the target volume supports the required attributes
#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>
typedef struct attrlist attrlist_t;
struct FInfoAttrBuf
unsigned long length;
fsobj_type_t objType;
char finderInfo[32];
};
typedef struct FInfoAttrBuf FInfoAttrBuf;
static int FInfoDemo(
const char *path,
const char *type,
const char *creator
)
{
int err;
attrlist_t attrList;
FInfoAttrBuf attrBuf;
assert( strlen(type) == 4 );
assert( strlen(creator) == 4 );
memset(&attrList, 0, sizeof(attrList));
attrList.bitmapcount = ATTR_BIT_MAP_COUNT;
attrList.commonattr = ATTR_CMN_OBJTYPE | ATTR_CMN_FNDRINFO;
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 = ATTR_CMN_FNDRINFO;
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 setattrlist() function call appeared in Darwin 1.3.1 (Mac OS X version
10.0).
Darwin December 15, 2003 Darwin
|