 |
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 );
LIBRARY
proplist.a, proplist.so
PARAMETERS
*path
Points to a file whose Extended File Attributes are to be retrieved
from its Property List.
follow
If nonzero, 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 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 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 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[] = {
"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 %s\n",
name, *value_len, value);
}
.
.
.
SEE ALSO
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 |
|