Xau(3)

NAME
       Xau library: XauFileName, XauReadAuth, XauLockAuth, XauUn-
       lockAuth, XauWriteAuth, XauDisposeAuth,  XauGetAuthByAddr,
       XauGetBestAuthByAddr - X authority database routines

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;

       Xauth *XauGetBestAuthByAddr (family,
                                    address_length, address,
                                    number_length, number,
                                    types_length, types, type_lengths)
            unsigned short family;
            unsigned short address_length;
            char *address;
            unsigned short number_length;
            char *number;
            int types_length;
            char **types;
            int *type_lengths;

       int XauLockAuth (file_name, retries, timeout, dead)
            char *file_name;
            int retries;

            int timeout;
            long dead;

       int XauUnlockAuth (file_name)
            char *file_name;

       XauDisposeAuth (auth)
            Xauth *auth;

DESCRIPTION
       XauFileName  generates the default authorization file name
       by first checking the XAUTHORITY environment  variable  if
       set,  else  it  returns  $HOME/.Xauthority.   This name is
       statically allocated and should not be freed.

       XauReadAuth reads the  next  entry  from  auth_file.   The
       entry  is  not statically allocated and should be freed by
       calling XauDisposeAuth.

       XuWriteAuth writes an authorization  entry  to  auth_file.
       It returns 1 on success, 0 on failure.

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

       XauGetBestAuthByAddr  is  similar   to   XauGetAuthByAddr,
       except that a list of acceptable authentication methods is
       specified.  Xau will choose the file entry  which  matches
       the  earliest  entry  in  this list (e.g., the most secure
       authentication method).  The types argument is an array of
       strings,   one  string  for  each  authentication  method.
       types_length specifies how many elements are in the  types
       array.  types_lengths is an array of integers representing
       the length of each string.

       XauLockAuth  does  the  work  necessary  to  synchronously
       update  an  authorization  file.   First it makes two file
       names, one with ``-c'' appended to  file_name,  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 syn-
       chronization troubles with  NFS,  a  dead  value  of  zero
       forces the files to be removed.  XauLockAuth makes retries
       attempts to create and link the file names, pausing  time-
       out  seconds  between each attempt.  XauLockAuth returns a
       collection of values depending on the results:

            LOCK_ERROR     A system error occurred, either a file_name
                           which is too long, or an unexpected failure from
                           a system call.  errno may prove useful.

            LOCK_TIMEOUT   retries attempts failed

            LOCK_SUCCESS   The lock succeeded.

       XauUnlockAuth undoes the work of XauLockAuth by  unlinking
       both the ``-c'' and ``-l'' file names.

       XauDisposeAuth  frees  storage allocated to hold an autho-
       rization entry.

SEE ALSO
       xauth(1) xdm(1) 

AUTHOR
       Keith Packard, MIT X Consortium