Index for Section 3

Alphabetical listing for G

Bottom of page

getproplist(3)
NAME
  getproplist, fgetproplist - Gets the Extended File Attributes of a file

SYNOPSIS
  #include <sys/proplist.h>

  int getproplist (
	  char *path,
	  int follow,
	  struct proplistname_args *args,
	  int nbytes,
	  char *buf,
	  int *min_buf_size );

  int fgetproplist (
	  int fd,
	  struct proplistname_args *args,
	  int nbytes,
	  char *buf,
	  int *min_buf_size );

PARAMETERS
  *path

      Points to a file whose Extended File Attributes are to be retrieved
      from its Property List.

  follow

      If non-zero, specifies that if the last component in *path is a
      symbolic link, then the link should be traversed.

  *args

      Points to the proplistname_args structure, defined in sys/proplist.h,
      that contains the following members:

	·
	pl_mask

	Contains system-wide Extended File Attributes.

	Note that if you are retrieving all the Extended File Attributes of a
	file, pl_mask must equal PLE_FLAG_ALL defined in sys/proplist.h.
	Also, if you are copying Extended File Attribute flags that match
	certain system-wide Extended File Attributes, the value of pl_mask
	should be formed by ORing the desired values of the system-wide
	Extended File Attributes.

	·
	pl_numnames

	Contains the number of Extended File Attributes names held in the
	names array, pl_names.



	·
	pl_names

	Contains a counted array of Extended File Attribute names.

	Note that the Extended File Attribute names are null terminated ASCII
	strings and that the last element of the array must be a null
	pointer.  Also, a null array pointer indicates all Extended File
	Attributes.

  nbytes

      Specifies the size of the Extended File Attribute buffer in bytes.

  *buf

      Points to the buffer that holds the Extended File Attributes.

  *min_buf_size

      Points to the buffer that holds the status of the size of the Extended
      File Attribute.

  fd

      Specifies a file descriptor for a file whose Extended File Attributes
      are to be retrieved from its Property List.  This parameter is used
      with the fgetproplist function.

DESCRIPTION
  The getproplist function gets the Extended File Attributes of a file
  pointed to by *path and places them in the Extended File Attribute buffer
  pointed to by nbytes.	 Which Extended File Attributes will be retrieved is
  determined by the parameters from the structure proplistname_args, defined
  in sys/proplist.h, that are passed to *args.	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).

  The fgetproplist function behaves the same as getproplist, except that it
  operates on a file descriptor rather than a pointer to a file.

NOTES
  Although not a requirement, you should use the get_proplist_entry(3)
  function to parse the attribute buffer returned by getproplist and
  fgetproplist.

EXAMPLES
       #include <sys/proplist.h>
       main()
       {
       char *ptr, *buf, *name, *value;
       int  *value_len, *flags, buffer_size, min_buffer_size, ret, nbytes;
       struct proplistname_args getargs;
       static char *names[] = {
	       "primary_name",
	       "secondary_name",
	       ""
       };

       /*
	* Malloc the buffer
	*/
       buffer_size = 8192
       buf = ptr = (char *)malloc(buffer_size);

	       .
	       .
	       .

       again:
       /*
	* Call the system call to load buffer with property list
	* entries.
	*/
       ret = getproplist("/tmp/foo", &getargs, buffer_size, buf,
			 &min_buffer_size);
       if (ret < 0) {
	       perror("getproplist");
	       free(buf);
	       exit(1);
       }
       /*
	* If buffer_size is not sufficient to store the name and value
	* pairs, malloc a bigger buffer and try again.
	*/
       if (ret == 0 && min_buffer_size) {
		       free(buf);
		       buf = (char *)malloc(min_buffer_size);
		       buffer_size = min_buffer_size;
		       goto again;
       }
       /*
	* Buffer contains ret bytes of name and value pairs
	*/
       ptr = buf;
       while (ret > 0) {
	       /*
		* Call getproplist_entry to initialize name and value
		* pointers to entries position within buffer.
		*/
	       ret -= get_proplist_entry(&name, &flags, &value_len, &value,
					 &ptr);
	       printf("name %s value len %d value %s0,
		       name, *value_len, value);
       }

	       .
	       .
	       .

RETURN VALUES
  If the function is successful, a value greater than zero is returned, which
  indicates the number of bytes of the Extended File Attribute that were
  copied into nbytes.  In addition, the intersection between the Extended
  File Attributes associated with the file pointed to by *path and the
  Extended File Attribute names specified in the expression args->pl_names
  are also returned.







  If the function is not successful, one of the following values is returned:

    ·  Zero

       A return value of zero indicates that one of the following conditions
       apply, depending on the value of the parameter *buf:

	 --
	 *buf is zero

	 If *buf is zero, the intersection between the Extended File
	 Attributes associated with the file pointed to by *path and the
	 Extended File Attribute names specified in the expression
	 args->pl_names was a null set.

	 --
	 *buf is greater than zero

	 If *buf is greater than zero, the size of the Extended File
	 Attribute buffer specified by the parameter *args was insufficient
	 to hold the intersection between the Extended File Attributes
	 associated with the file pointed to by *path and the Extended File
	 Attribute names specified in the parameter args->pl_names.  Note
	 that the value contained in *buf is the number of bytes required to
	 retrieve successfully the requested Extended File Attributes.

    ·  The integer -1

       If the integer -1 is returned, the function was unsuccessful 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.

  [EFAULT]  A problem was encountered with the Extended File Attribute.

  [EINVAL]  A problem was encountered with the Extended File Attribute.

  [EIO]	    There was an error reading 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 ot have the appropriate system
	    priviliges to access the requested Extended File Attribute, for
	    example, DEC_AUDIT_PROPLISTFLAG.

RELATED INFORMATION
  Functions: open(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 G

Top of page