getproplist, fgetproplist - gets the Extended File
Attributes of a file
#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 );
proplist.a, proplist.so
Points to a file whose Extended File Attributes are to be
retrieved from its Property List. If nonzero, 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/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. 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.
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.
Although not a requirement, you should use the get_proplist_entry(3) function to parse the attribute buffer
returned by getproplist() and fgetproplist().
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.
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 not have the appropriate
system privileges to access the requested Extended
File Attribute, for example, DEC_AUDIT_PROPLISTFLAG.
#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); }
.
.
.
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.
getproplist(3)
[ Back ] |
