Museum

     DBLOCK(S)                 UNIX System V                 DBLOCK(S)



     Name
          dblock - lock the entire Authentication database

     Syntax
          #include <sys/types.h>
          #include <sys/security.h>
          #include <sys/audit.h>
          #include <prot.h>

          void ensure_db_lock (decibel)
          int decibel;

          int db_lock (decibel)
          int decibel;

          int db_unlock (decibel)
          int decibel;

          int file_lock (attempts, delay, fd, decibel)
          register int attempts;
          int delay;
          int fd;
          int decibel;

          int file_unlock (name, fd, decibel)
          register char *name;
          register int fd;
          int decibel;

          void enter_quiet_zone ()

          void exit_quiet_zone ()

          int make_transition_files (pathname, ptemppathname,
          poldpathname)
          register char *pathname;
          register char **ptemppathname;
          register char **poldpathname;

          int replace_file (temppathname, pathname, oldpathname)
          register char *temppathname;
          register char *pathname;
          register char *oldpathname;

     Description
          These routines support update locking to the authentication
          database.  Ensure_db_lock guarantees that the database is
          locked now.  The process will exit if the lock cannot occur.
          If the decibel argument is AUTH_QUIET, the locking will be
          done without interruptions from signals.  Db_lock tries to
          lock the database.  If the decibel argument is AUTH_QUIET,
          the locking will be done without interruptions from signals.
          It returns 1 if the lock occurred and 0 if the lock could
          not be done.  Db_unlock removes a lock previously placed by
          db_lock.  If the decibel argument is AUTH_QUIET, the signal
          states saved from ensure_db_lock or db_lock are restored.
          (The decibel argument must match when creating and removing
          the same lock.) db_unlock returns 1 if it successfully
          worked and 0 if there were no lock or the lock could not be
          removed.

          The more generic file_lock routine will lock the file opened
          as fd.  It will try for attempts times, spaced at delay
          seconds apart.  If the decibel argument is AUTH_QUIET, the
          locking will be done without interruptions from signals.  If
          the file can be locked, the routine returns a 1;  otherwise,
          it returns a 0.  The companion routine file_unlock unlocks
          the file with name and descriptor fd and returns 1 if
          successful and 0 if not.  The decibel argument used as in
          the db_unlock case.

          The enter_quiet_zone and exit_quiet_zone 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 distrupt the entire operation would leave the
          system in an insecure state or a state from which it is hard
          to recover.

          Enter_quiet_zone turns off all keyboard signals, namely
          SIGHUP, SIGINT and SIGQUIT.  It saves the previous state of
          each of those signals.

          Exit_quiet_zone must be called after a call to
          enter_quiet_zone.  Exit_quiet_zone restores those signal
          states set by enter_quiet_zone.

          The only legal way to use these routines is in the sequence:

               enter_quiet_zone();
               ...
               exit_quiet_zone();
               ...
               enter_quiet_zone();
               ...
               exit_quiet_zone();
               ...
               enter_quiet_zone();
               ...
               exit_quiet_zone();
               ...

          The routines make_transition_files and replace_file are used
          together to update one of the authentication database files.

          Make_transition_files takes the input argument pathname and
          creates two new file names.  The file names are returned to
          the reference of pointers poldpathname and ptemppathname.
          It is guaranteed that these two names cannot appear as
          database entries due to characters they use in the name.
          Poldpathname refers to the name in which to place the
          existing file referenced by pathname should there be
          trouble.  Ptemppathname refers to the new file being
          constructed to replace pathname.  Note that malloc(S) is
          used to create space for poldpathname and ptemppathname and
          that files are not actually opened or otherwise referenced
          by make_transition_files.  A return value of 1 means the
          names were created and a return of 0 means they were not.

          Replace_file uses the same arguments to manipulate the
          actual files.  It expects that pathname references the
          existing file, ptemppathname references the newly created
          file, and poldpathname references the place pathname will be
          moved to should an error occur in placing the new file in
          pathname.  A return value of 1 means the file movements
          worked successfully and 0 means they were not.  Replace_file
          removes the space allocated for the names in
          make_transition_files.

     Notes
          These routines only work as advertised when
          set_auth_parameters is called as the first item in main().

     Files
          /tcb/files/auth/lock

     See Also
          lockf(S), signal(S), malloc(S)

                                                (printed 6/20/89)