putpfileattr Subroutine

Purpose

Accesses the privileged file security information in the privileged file database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int putpfileattr (File, Attribute, Value, Type)
    char *File;
    char *Attribute;
    void *Value;
    int Type;

Description

The putpfileattr subroutine writes a specified attribute into the privileged file database. If the database is not open, this subroutine opens the database implicitly for reading and writing. Data that is changed by the putpfileattr and putpfileattrs subroutines must be explicitly committed by calling the putpfileattr subroutine with a Type parameter specifying SEC_COMMIT. Until all the data is committed, only these subroutines within the process return written data.

New entries in the privileged file databases must first be created by invoking the putpfileattr subroutine with the SEC_NEW type.

Parameters

Table 1. Parameters
Item	Description
`File`	The file name. The value should be the full path to the file on the system. This parameter must be specified unless the `Type` parameter is `SEC_COMMIT`.
`Attribute`	Specifies which attribute is read. The following possible attributes are defined in the usersec.h file: S_READAUTHS Authorizations required to read the file using the pvi command. A total of eight authorizations can be defined. The attribute type is `SEC_LIST`. S_WRITEAUTHS Authorizations required to write to the file using the pvi command. A total of eight authorizations can be defined. The attribute type is `SEC_LIST`.
`Value`	Specifies a buffer, a pointer to a buffer, or a pointer to a pointer depending on the `Attribute` and `Type` parameters. See the `Type` parameter for more details.
`Type`	Specifies the type of attribute expected. Valid types are defined in the usersec.h file and include: SEC_LIST The format of the attribute is a series of concatenated strings, each null-terminated. The last string in the series is terminated by two successive null characters. For the putpfileattr subroutine, the user should supply a character pointer. SEC_COMMIT For the putpfileattr subroutine, this value specified by itself indicates that changes to the security attributes of the named file are to be committed to the permanent storage. The `Attribute` and `Value` parameters are ignored. If no file is specified, the changes to all modified files are committed to the permanent storage. SEC_DELETE If the `Attribute` parameter is specified, then the corresponding attribute is deleted from the privileged file database. If no `Attribute` parameter is specified, then the entire file definition is deleted from the privileged file database. SEC_NEW Creates a new file in the privileged file database when it is specified with the putpfileattr subroutine.

Security

Files Accessed

Table 2. File Accessed
File	Mode
/etc/security/privfiles	rw

Return Values

If successful, the putpfileattr subroutine returns 0. Otherwise, a value of -1 is returned and the errno global value is set to indicate the error.

Error Codes

If the putpfileattr subroutine fails, one of the following errno values can be set:

Table 3. Error Codes
Item	Description
`EINVAL`	The `File` parameter is `NULL` and the `Type` parameter is `SEC_NEW` or `SEC_DELETE`.
`EINVAL`	The `File` parameter is `default` or `ALL`.
`EINVAL`	The `Attribute` parameter does not contain one of the defined attributes or is `NULL`.
`EINVAL`	The `Type` parameter does not contain one of the defined values.
`EINVAL`	The `Value` parameter does not point to a valid buffer or to the valid data for this type of attribute.
`ENOENT`	The file specified by the `File` parameter does not exist.
`EPERM`	Operation is not permitted.