create_file_securely(S)        6 January 1993        create_file_securely(S)


 Name

    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

    createfilesecurely(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 con-
    trol database entry that are used by this routine include:


    fowner  Owner of the file

    fgroup  Group of the file

    fmode   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 AUTHSILENT or AUTHVERBOSE. AUTHVERBOSE 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 AUTHVERBOSE 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 AUTHSILENT, 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 AUTHVERBOSE.

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

    createfilesecurely(S) returns a status code that provides detailed in-
    formation on the result of the create operation. The return codes are:


    CFSGOODRETURN
                The file was created successfully and all of the attributes
                specified in the file control database entry were success-
                fully set on the new file.

    CFSCANNOTOPENFILE
                The routine was unable to create the file identified by path.

    CFSNOFILECONTROLENTRY
                There was not a file control database entry for path.

    CFSCANNOTCHGMODE
                The permissions specified by the file control database could
                not be set on the created file.

    CFSCANNOTCHGOWNERGROUP
                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 -lprots,
    together with -lx.

 See also

    getprfient(S), files(F).

 Standards conformance

    createfilesecurely(S) is not part of any currently supported standard;
    it is an extension of AT&T System V provided by the Santa Cruz Operation.