Content-type: text/html Man page of setproplist

setproplist

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

setproplist, fsetproplist - Assigns Extended File Attributes to a file  

SYNOPSIS

#include <sys/proplist.h> int setproplist (        char *path,
       int follow,
       int nbytes,
       char *buf );
int fsetproplist (        int fd,
       int nbytes,
       char *buf );
 

PARAMETERS

Points to a file that is to be assigned Extended File Attributes.
If non-zero, specifies that if the last component in *path is a symbolic link, then the link should be traversed.
Specifies the size of *buf in bytes.
Points to a buffer of Extended File Attributes.
Specifies a file descriptor for a file that is to be assigned Extended File Attributes. This parameter is used with the fsetproplist function.
 

DESCRIPTION

The setproplist function assigns a buffer of Extended File Attributes, pointed to by nbytes, to a file pointed to by *path. The Extended File Attribute buffer is defined in sys/proplist.h. 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). One or several Extended File Attributes can be assigned to a file each time setproplist is called. Also, both new and existing Extended File Attributes can be assigned to a file, although if you specify an Extended File Attribute name that already exists in the Property List and a new value to pair with it, the new value will replace the existing value.

Note that any space allocated to a UFS file's Property List is accounted for in the user's quota statistics and must be accounted for in the st_blocks field returned by stat(2).

The fsetproplist function behaves the same as setproplist, except that it operates on a file descriptor rather than a pointer to a file.  

NOTES

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).  

RESTRICTIONS

If a system failure occurs when the Extended File Attributes are being written to disk, one of the three following conditions may apply to each Extended File Attribute, since there are no ordering guarantees when several Extended File Attributes are being updated: The new value for an existing Extended File Attribute was written to disk. The new value for an existing Extended File Attribute was not written to disk and the old value still exists. A new value for a Extended File Attribute that did not previously exist was not written to disk.  

EXAMPLES

#include <sys/proplist.h> main() { char *ptr, *buf, *name, *value; int *value_len, *flags, buffer_size, min_buffer_size, ret, nbytes; 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 %d, 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, a value greater than or equal to zero is returned which represents the number of bytes of the Extended File Attributes that were assigned to the file pointed to by *path and written to disk. In addition, the change time of the file pointed to by *path is marked for update.

If unsuccessful, the integer -1 is returned 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.

The calling program was not the owner of the file and the process does not have the appropriate system privilige. A problem was encountered with the Extended File Attribute buffer. A problem was encountered with the Extended File Attribute buffer. There was an error reading or writing 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 appropirate system privilige to access the requested Extended File Attribute, for example, DEC_AUDIT_PROPLISTFLAG. The file system is mounted read-only.
 

RELATED INFORMATION

Functions: open(2), stat(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.

delim off


 

Index

NAME
SYNOPSIS
PARAMETERS
DESCRIPTION
NOTES
RESTRICTIONS
EXAMPLES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:44 GMT, October 02, 2010