 |
Index for
Section 3 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
setproplist(3)
NAME
setproplist, fsetproplist - assigns Extended File Attributes to a file
SYNOPSIS
#include <sys/proplist.h>
int setproplist(
char *path,
int follow,
int nbytes,
char *buf );
int fsetproplist(
int fd,
int nbytes,
char *buf );
LIBRARY
proplist.a, proplist.so
PARAMETERS
*path
Points to a file that is to be assigned Extended File Attributes.
follow
If nonzero, specifies that if the last component in *path is a symbolic
link, then the link should be traversed.
nbytes
Specifies the size of *buf in bytes.
*buf
Points to a buffer of Extended File Attributes.
fd Specifies a file descriptor for a file that is to be assigned Extended
File Attributes. This parameter is used with the fsetproplist()
function.
DESCRIPTION
The setproplist() function assigns a buffer of Extended File Attributes,
pointed to by nbytes, to a file pointed to by *path. The Extended File
Attribute buffer is defined in sys/proplist.h. An Extended File Attribute
is a name and value pair that is contained in a variable-sized structure
called a Property List. A Property List is part of a file's metadata and
can contain abstract name and value pairs (Extended File Attributes) that
can be set either by the operating system (for example, ACLs and
privileges) or by a user-level application (for example, PC File
Attributes). One or several Extended File Attributes can be assigned to a
file each time setproplist() is called. Also, both new and existing
Extended File Attributes can be assigned to a file, although if you specify
an Extended File Attribute name that already exists in the Property List
and a new value to pair with it, the new value will replace the existing
value.
Note that any space allocated to a UFS file's Property List is accounted
for in the user's quota statistics and must be accounted for in the
st_blocks field returned by stat(2).
The fsetproplist() function behaves the same as setproplist(), except that
it operates on a file descriptor instead of a pointer to a file.
NOTES
Although not a requirement, you should use the sizeof_proplist_entry(3) and
add_proplist_entry(3) functions to initialize the Extended File Attribute
buffer passed to setproplist(3) and fsetproplist(3).
RESTRICTIONS
If a system failure occurs when the Extended File Attributes are being
written to disk, one of the three following conditions may apply to each
Extended File Attribute because there are no ordering guarantees when
several Extended File Attributes are being updated:
· The new value for an existing Extended File Attribute was written to
disk.
· The new value for an existing Extended File Attribute was not written
to disk and the old value still exists.
· A new value for a Extended File Attribute that did not previously
exist was not written to disk.
RETURN VALUES
If successful, a value greater than or equal to zero is returned. The value
represents the number of bytes of the Extended File Attributes that were
assigned to the file pointed to by *path and written to disk. In addition,
the change time of the file pointed to by *path is marked for update.
If unsuccessful, the integer -1 is returned and errno is set to indicate
the error.
ERRORS
In addition to errors associated with open(2), the function will fail if:
[EACCESS]
Search permission was denied for a directory in *path.
The calling program was not the owner of the file and the process does
not have the appropriate system privilege.
[EFAULT]
A problem was encountered with the Extended File Attribute buffer.
[EINVAL]
A problem was encountered with the Extended File Attribute buffer.
[EIO]
There was an error reading or writing some portion of the Property
List.
[EOPNOTSUPP]
The Extended File Attribute could not be associated with the file
pointed to by *path.
[EPERM]
The calling program does not have the appropriate system privilege to
access the requested Extended File Attribute, for example,
DEC_AUDIT_PROPLISTFLAG.
[EROFS]
The file system is mounted read-only.
EXAMPLES
#include <sys/proplist.h>
main()
{
char *ptr, *buf, *name, *value;
int *value_len, *options, buffer_size, min_buffer_size, ret, nbytes;
static char *names[] = {
"primary_name",
"secondary_name",
""
};
/*
* How big a buffer do I need to store my name and value
* pair in a property list ?
*/
buffer_size = sizeof_proplist_entry("primary_name", 18);
buffer_size += sizeof_proplist_entry("secondary_name", 13);
/*
* Malloc the buffer
*/
buf = ptr = (char *)malloc(buffer_size);
/*
* Call add_proplist_entry to initialize the buffer with
* the first name and value pair.
*/
ret = add_proplist_entry("primary_name", 0, 18,
"Primary Name Value", &ptr);
/*
* Call add_proplist_entry to initialize the buffer with
* the second name and value pair.
*/
ret += add_proplist_entry("secondary_name", 0, 13,
"Another Value", &ptr);
if (ret != buffer_size) {
printf("ret %d != buffer_size %d\n", ret, buffer_size);
free(buf, buffer_size);
exit(1);
}
/*
* Buffer now contains both name and value pairs. Call setproplist
* system call to actually associate name and value pairs to
* file.
*/
nbytes = setproplist("/tmp/foo", 1, buffer_size, buf);
if (nbytes < 0 || nbytes != buffer_size) {
perror("setproplist");
free(buf);
exit(1);
}
SEE ALSO
Functions: open(2), stat(2), add_proplist_entry(3), delproplist(3),
fdelproplist(3), fgetproplist(3), fsetproplist(3), get_proplist_entry(3),
getproplist(3), setproplist(3), sizeof_proplist_entry(3)
Files: proplist(4), sys/proplist.h
|
Index for
Section 3 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|