dblock(S)                      6 January 1993                      dblock(S)


 Name

    dblock: enter_quiet_zone, exit_quiet_zone, make_transition_files,
    replace_file - authentication database locking routines

 Syntax


    cc  . . .  -lprot -lx


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

    void enter_quiet_zone ()

    void exit_quiet_zone ()

    int make_transition_files (pathname, ptempp, poldp)
    register char *pathname;
    register char **ptempp;
    register char **poldp;

    int replace_file (tempp, pathname, oldp)
    register char *tempp;
    register char *pathname;
    register char *oldp;


 Description

    The enterquietzone(S) and exitquietzone(S) routines provide a way to
    enter and exit regions of code where the process is undisturbed by all
    external signals.  This is helpful on sensitive regions of code where the
    security state is being altered and to disrupt the entire operation would
    leave the system in an insecure state or a state from which it is hard to
    recover.

    enterquietzone() blocks off all keyboard signals, including SIGHUP,
    SIGINT, and SIGQUIT.  The result of this blocking is that delivery of any
    signals will be delayed until they are unblocked in the call to
    exitquietzone().

    Pairs of calls to enterquietzone() and exitquietzone() may be nested,
    but it is important that the number of exitquietzone() calls match the
    number of enterquietzone() calls.  Signals are blocked on the first
    call to enterquietzone(), and only unblocked on the last call to
    exitquietzone().

    The routines maketransitionfiles(S) and replacefile(S) are used
    together to update one of the authentication database files.

    maketransitionfiles() takes the input argument pathname and generates
    two new file names.  Pointers to the new file names are stored in the
    locations referenced by the pointers poldp and ptempp.  The pointer
    referenced by poldp points to the name used to rename the existing file
    referenced by pathname so that it may be recovered if the update fails.
    The pointer referenced by ptempp points to the name to be used for the
    new file intended to replace the existing file referenced by pathname.
    Note that malloc(S) is used to create space for poldp and ptempp, and
    that files are not actually opened or otherwise referenced by
    maketransitionfiles().

    replacefile() uses the same arguments (those given to and modified by a
    previous call to maketransitionfiles()) to manipulate the actual files.
    It expects that pathname references the existing file, tempp references
    the newly created file, and oldp references the place that the existing
    file is to be moved to should an error occur in placing the new file in
    pathname.  replacefile() frees the space allocated for the names in
    maketransitionfiles().

 Notes

    Any program calling these routines should call setauthparameters(S) as
    the first action in main().

 Return values

    maketransitionfiles() returns a value of 1 if the names were generated,
    and 0 if they were not.

    replacefile() returns a value of 1 if the file operations were success-
    ful and 0 if they were not.

 See also

    identity(S), sigprocmask(S), malloc(S)

 Standards conformance

    The dblock routines are extensions of AT&T System V provided by the Santa
    Cruz Operation.