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 Attributes.

	      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  fsetpro-
	      plist 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 rather than 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, 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 Attribute 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,		  "Another 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 indicate 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  problem  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 Property 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_pro-
       plist_entry(3), getproplist(3), setproplist(3), sizeof_proplist_entry(3).

       Files: proplist(4), sys/proplist.h.

       delim off

																    setproplist(3)