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. 

flags

Specifies 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, Digital recommends 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). 

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;
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);
        }

. 
.
.

RETURN VALUES

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

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: proplist(4), sys/proplist.h.