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 );

PARAMETERS
  *path

      Points to a file that is to be assigned Extended File Attributes.

  follow

      If non-zero, 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 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:

  [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 privilige.

  [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 appropirate system
	    privilige to access the requested Extended File Attribute, for
	    example, DEC_AUDIT_PROPLISTFLAG.

  [EROFS]   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_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