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

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:
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:

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.