setproplist(3)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
Points to a file that is to be assigned Extended File Attributes. If
nonzero, specifies that if the last component in *path is a symbolic
link, then the link should be traversed. Specifies the size of *buf in
bytes. Points to a buffer of Extended File Attributes. 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 sys‐
tem (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 indi‐
cate the error.
ERRORS
In addition to errors associated with open(2), the function will fail
if: 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. A prob‐
lem was encountered with the Extended File Attribute buffer. A
problem was encountered with the Extended File Attribute buffer.
There was an error reading or writing some portion of the Prop‐
erty List. The Extended File Attribute could not be associated
with the file pointed to by *path. The calling program does not
have the appropriate system privilege to access the requested
Extended File Attribute, for example, DEC_AUDIT_PROPLISTFLAG.
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); buf‐
fer_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_pro‐
plist_entry(3), getproplist(3), setproplist(3), sizeof_pro‐
plist_entry(3)
Files: proplist(4), sys/proplist.h
setproplist(3)
