522 lines
12 KiB
Groff
522 lines
12 KiB
Groff
.\" 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 XXXbitmapcount
|
|
.
|
|
.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
|
|
.
|
|
.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.
|
|
.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.
|
|
.
|