add_proplist_entry(3) — Subroutines

NAME

add_proplist_entry − adds an Extended File Attribute to the Extended File Attribute buffer

SYNOPSIS

#include <sys/proplist.h>
int add_proplist_entry(
        char ∗name,
        int flags,
        int value_size,
        char ∗value,
        char ∗∗bufptr );

PARAMETERS

∗name
Points to the Extended File Attribute name, a null-terminated ASCII string.

flagsSpecifies system-wide attributes for Extended File Attribute entries. These system-wide attributes are defined in sys/proplist.h.

value_size
Specifies the size in bytes of the Extended File Attribute value.

∗value
Points to the value of the Extended File Attribute.

∗∗bufptr
Points to the Extended File Attribute buffer.

DESCRIPTION

The add_proplist_entry() function initializes an Extended File Attribute buffer, pointed to by ∗∗bufptr, with the Extended File Attribute specified by the ∗name and ∗value parameters. The function can be called repeatedly because it advances the Extended File Attribute buffer pointer ∗∗bufptr to the end of the current entry. 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).

Although not a requirement, it is recommended that you use the sizeof_proplist_entry(3) and add_proplist_entry(3) functions to initialize the Extended File Attribute buffer passed to setproplist(3) and fsetproplist(3).

RETURN VALUES

If successful, the function returns the number of bytes copied into the Extended File Attribute buffer.

EXAMPLES

#include <sys/proplist.h>
main() {
char ∗ptr, ∗buf, ∗name, ∗value;
int ∗value_len, ∗options, buffer_size, min_buffer_size, ret, nbytes;
struct proplistname_args;
static char ∗names[] = {
        "primary_name",
        "secondary_name",
        ""
};
/∗
∗ How big a buffer do I need to store my name and value
∗ pair in a property list ?
∗/
buffer_size = sizeof_proplist_entry("primary_name", 18);
buffer_size += sizeof_proplist_entry("secondary_name", 13);
/∗
∗ Malloc the buffer
∗/
buf = ptr = (char ∗)malloc(buffer_size);
/∗
∗ Call add_proplist_entry to initialize the buffer with
∗ the first name and value pair.
∗/
ret = add_proplist_entry("primary_name", 0, 18,
"Primary Name Value", &ptr);
/∗
∗ Call add_proplist_entry to initialize the buffer with
∗ the second name and value pair.
∗/
ret += add_proplist_entry("secondary_name", 0, 13,
"Another Value", &ptr);
if (ret != buffer_size) {
printf("ret %d != buffer_size %d0", ret, buffer_size);
free(buf, buffer_size);
exit(1);
}
/∗
∗ Buffer now contains both name and value pairs. Call setproplist
∗ system call to actually associate name and value pairs to
∗ file.
∗/
nbytes = setproplist("/tmp/foo", 1, buffer_size, buf);
        if (nbytes < 0 || nbytes != buffer_size) {
                perror("setproplist");
                free(buf);
                exit(1);
        }

Museum

Related Articles