getproplist man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

getproplist(3)							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 );

LIBRARY
       proplist.a, proplist.so

PARAMETERS
       Points  to  a  file  whose Extended File Attributes are to be retrieved
       from its Property List.	If nonzero, specifies that if the last	compo‐
       nent  in	 *path	is a symbolic link, then the link should be traversed.
       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/pro‐
	      plist.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 -- Con‐
	      tains 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.	  Specifies  the  size	of  the	 Extended File
	      Attribute buffer in bytes.  Points to the buffer that holds  the
	      Extended	File  Attributes.  Points to the buffer that holds the
	      status of the size of the Extended File Attribute.  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 buf‐
       fer  pointed  to	 by  nbytes.  Which  Extended  File Attributes will be
       retrieved is determined by the parameters from the structure  proplist‐
       name_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 sys‐
       tem (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 instead of 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().

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  con‐
	      ditions  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  insuffi‐
	      cient  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: Search permission was denied for a directory in *path.   A  problem
       was  encountered	 with  the  Extended  File  Attribute.	 A problem was
       encountered with the Extended File Attribute.  There was an error read‐
       ing  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 appropriate system privileges to access the
       requested Extended File Attribute, for example, DEC_AUDIT_PROPLISTFLAG.

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[]  =	{	 "pri‐
       mary_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("getpro‐
       plist");	     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 %s\n",	   name, *value_len, value); }
	       .
	       .
	       .

SEE ALSO
       Functions:  open(2),  add_proplist_entry(3),  delproplist(3),  fdelpro‐
       plist(3), fgetproplist(3), fsetproplist(3), get_proplist_entry(3), get‐
       proplist(3), setproplist(3), sizeof_proplist_entry(3).

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

								getproplist(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net