proplist(4) [osf1 man page]
proplist(4) Kernel Interfaces Manual proplist(4) NAME
proplist - The storing, parsing, and retrieving of Extended File Attributes DESCRIPTION
Tru64 UNIX supports the storing, parsing, and retrieving of Extended File Attributes. 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). Since Extended File Attributes are treated as an extension to a file's metadata, they are synchronously updated, thereby ensuring consis- tency. Note that Extended File Attributes set by user-level applications are treated as opaque and can be virtually anything. To ensure that all Property List names are unique, you must register your Property List names with Compaq. Those Property List names with a prefix are reserved by Compaq. In the case of conflicts, Compaq reserves the right to arbitrate the naming conventions of Property Lists. To register a Property List name, send a request by network mail to or write to: Tru64 UNIX File System Group ATTN: Property List Administrator Compaq Computer Corporation 110 Spit Brook Road Nashua, NH. 03062-2698 M/S ZKO3-3/U14 Several user-level routines, listed in the Related Information section, work together to manipulate Extended File Attributes. For example: To set attributes, you use the sizeof_proplist_entry(3) and add_proplist_entry(3) routines to initialize the Extended File Attribute buffer passed to setproplist(3) or fsetproplist(3). To fetch attributes, you use getproplist(3) or fgetproplist(3). To parse the attribute buf- fer returned by setproplist(3) or fsetproplist(3), use the get_proplist_entry(3) routine. The format of the Extended File Attributes buffer, the values of the system-wide properties, and the format of the Property List structures are all defined in sys/proplist.h. NOTES
Extended File Attributes are supported by the Advanced File System (AdvFS), the UNIX File System (UFS), and the Network File System (NFS). The latter through the use of the proplistd daemon and the mount -o proplist command. The archive utilities and support files with Extended File Attributes. However, third-party archive utilities may not support Extended File Attributes and, consequently, if they are used on files with Extended File Attributes, the Extended File Attributes will be lost. RELATED INFORMATION
Functions: 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: libproplist.a, libproplist.so, sys/proplist.h, acl(4). Daemons: proplistd(8). delim off proplist(4)
Check Out this Related Man Page
getproplist(3) Library Functions Manual 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
Points to a file whose Extended File Attributes are to be retrieved from its Property List. If non-zero, specifies that if the last component 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 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. 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 buffer 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 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 pro- plistname_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: 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 reading 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 ot have the appropriate system priviliges to access the requested Extended File Attribute, for example, DEC_AUDIT_PROPLIST- FLAG. RELATED INFORMATION
Functions: open(2), add_proplist_entry(3), delproplist(3), fdelproplist(3), fgetproplist(3), fsetproplist(3), get_proplist_entry(3), get- proplist(3), setproplist(3), sizeof_proplist_entry(3). Files: proplist(4), sys/proplist.h. delim off getproplist(3)