*** UNIX MANUAL PAGE BROWSER ***

setproplist(3) Library Functions Manual 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 ); PARAMETERS Points to a file that is to be assigned Extended File Attrib- utes. If non-zero, 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 fset- proplist 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 At- tribute 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 exam- ple, 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 ac- counted 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 rather than a pointer to a file. NOTES Although not a requirement, Digital recommends that you use the sizeof_proplist_entry(3) and add_proplist_entry(3) functions to ini- tialize 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, since 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 At- tribute that did not previously exist was not written to disk. EXAMPLES #include <sys/proplist.h> main() { char *ptr, *buf, *name, *value; int *value_len, *flags, 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, "An- other Value", &ptr); if (ret != buffer_size) { printf("ret %d != buffer_size %d0, 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); } . . . RETURN VALUES If successful, a value greater than or equal to zero is returned which 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 privilige. 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 appropirate system privilige to access the requested Extended File Attribute, for example, DEC_AUDIT_PROPLISTFLAG. The file system is mounted read-only. RELATED INFORMATION Functions: open(2), stat(2), add_proplist_entry(3), delproplist(3), fdelproplist(3), fgetproplist(3), fsetproplist(3), get_proplist_en- try(3), getproplist(3), setproplist(3), sizeof_proplist_entry(3). Files: proplist(4), sys/proplist.h. delim off setproplist(3)