create_file_securely(S)

create_file_securely -- create a file using an attribute specification from the file control database

Syntax

cc . . . -lprot -lx

#include <sys/types.h>
#include <prot.h>

int create_file_securely (path, mode, purpose)
char *path;
int mode;
char *purpose;

Description

create_file_securely(S) is used to create a file and to assign to that file attributes specified for it in the file control database, /etc/auth/system/files. Attributes that may be specified for a file control database entry that are used by this routine include:

f_owner: Owner of the file
f_group: Group of the file
f_mode: File permission bits

Other attributes supported by the file control database have no effect during the creation of a file but are intended for use by programs such as integrity(ADM).

The path argument is the name of a file to be created using attributes from the file control database. The file name should match exactly a file name entry in the file control database.

mode is either AUTH_SILENT or AUTH_VERBOSE. AUTH_VERBOSE mode results in signals being blocked until the routine is finished and also will result in the generation of audit records for failure conditions. Additionally, since the routine is used to create temporary files on behalf of callers, a temporary file may already exist at the time the routine is invoked. The use of AUTH_VERBOSE mode allows the routine to wait for any existing temporary file to be removed, using an adaptive time-out/retry mechanism. This allows synchronization of simultaneous database updates. If the mode is specified as AUTH_SILENT, signals are not blocked by the routine nor are audit records generated when an operation fails. Additionally, if the entry refers to a temporary file and that file already exists, no attempt is made to wait until it is removed.

The purpose argument is a pointer to a string identifying the reason for using the routine to create the file. This string is used as part of audit record when the mode is AUTH_VERBOSE.

The routine sets the attributes of the file according to a specific sequence designed to minimize the need for the calling process to have certain effective privileges. The file is first created using the O_EXCL option and the open(S) system call. This will fail if the file already exists. Once the file has been created, it is closed since certain attributes can only be set on the file if the file is not in use. If the file control database entry does not specify an owner, the owner of the file will be set to the real user id of the process. Likewise, if the entry does not specify the file group, it is set to the real group id of the process. If a value for mode is not specified for the file, then mode will be set to its default value, 0.

The file permissions are set according to the file control database entry, if a value is present, or to a mode of 0. This is done using the chmod(S) system call while the file is still owned by the calling user.

Lastly, the owner and group of the file are set using the chown(S) system call.

Diagnostics

create_file_securely(S) returns a status code that provides detailed information on the result of the create operation. The return codes are:

CFS_GOOD_RETURN: The file was created successfully and all of the attributes specified in the file control database entry were successfully set on the new file.
CFS_CAN_NOT_OPEN_FILE: The routine was unable to create the file identified by path.
CFS_NO_FILE_CONTROL_ENTRY: There was not a file control database entry for path.
CFS_CAN_NOT_CHG_MODE: The permissions specified by the file control database could not be set on the created file.
CFS_CAN_NOT_CHG_OWNER_GROUP: The owner/group specified in the file control database entry could not be set for the created file.

If the file can not be created or an attempt to set any of the attributes specified by the file control database entry fails, the routine will return one of the above failure codes. If the failure resulted from the inability to set an attribute on the created file, the file is also removed before returning.

Note

Programs using this routine must be compiled with -lprot or -lprot_s, together with -lx.

Standards conformance