XauFileName(3X)                                   XauFileName(3X)



NAME
     XauFileName, XauReadAuth, XauLockAuth, XauUnlockAuth,
     XauWriteAuth,  XauGetAuthByAddr  -  manage  the  X authority
     database

SYNOPSIS
     #include <X11/Xauth.h>

     typedef struct xauth {
       unsigned short family;
       unsigned short address-length;
       char *address;
       unsigned short number-length;
       char *number;
       unsigned short name-length;
       char *name;
       unsigned short data-length;
       char *data;
     } Xauth;

     char *XauFileName ()

     Xauth *XauReadAuth(auth-file)
     FILE *auth-file;

     int XauWriteAuth(auth-file, auth)
     FILE *auth-file;
     Xauth *auth;

     Xauth XauGetAuthByAddr(family, address-length, address,
     number-length, number)
     unsigned short family;
     unsigned short address-length;
     char *address;
     unsigned short number-length;
     char *number;

     int XauLockAuth(file, retries, timeout, dead)
     char *file;
     int retries;
     int timeout;
     long dead;

     int XauUnlockAuth(file)
     char *file;
     XauDisposeAuth(auth)
     Xauth *auth;

DESCRIPTION
     The XauFileName function generates the default authorization
     filename by first checking the XAUTHORITY environment vari-
     able if set, else it returns $HOME/.Xauthority.  This name



November, 1990                                                  1

XauFileName(3X)                                   XauFileName(3X)



     is statically allocated and should not be freed.

     The XauReadAuth function reads the next entry from auth-
     file.  The entry is not statically allocated and should be
     freed by calling XauDisposeAuth.

     The XuWriteAuth function writes an authorization entry to
     auth-file.  It returns 1 on success, 0 on failure.

     The XauGetAuthByAddr function searches for an entry that
     matches the given network address/display number pair.  The
     entry is not statically allocated and should be freed by
     calling XauDisposeAuth.

     The XauLockAuth function does the work necessary to synchro-
     nously update an authorization file.  First it makes two
     filenames, one with -c appended to file, the other with -l
     appended.  If the -c file already exists and is more than
     dead seconds old, XauLockAuth removes it and the associated
     -l file.  To prevent possible synchronization troubles with
     the Network File System (NFS), a dead value of 0 forces the
     files to be removed.  XauLockAuth makes retries attempts to
     create and link the filenames, pausing timeout seconds
     between each attempt. XauLockAuth returns LOCK_SUCCESS to
     indicate that the lock was make successfully.

     The XauUnlockAuth function undoes the work of XauLockAuth by
     unlinking both the -c and -l filenames.

     The XauDisposeAuth function frees storage allocated to hold
     an authorization entry.

ERRORS
     LOCK_ERROR
             A system error occurred. Either file is too long, or
             an unexpected failure from a system call occurred.

     LOCK_TIMEOUT
             The number of retries specified by retries failed.

     The XauLockAuth function can generate LOCK_ERROR and
     LOCK_TIMEOUT errors.

NOTES
     Copyright 1988, Massachusetts Institute of Technology.
     See X(1X) for a full statement of rights and permissions.

     Author: Keith Packard, MIT X Consortium

SEE ALSO
     xauth(1X), xdm(1X)




2                                                  November, 1990