AFAUTH(1)			     .SH			    AFAUTH(1)
NAME									 NAME
AFauFileName,							AFauFileName,


  AFauReadAuth,	AFauLockAuth, AFauUnlockAuth, AFauWriteAuth, AFauGetAuth-
  ByAddr - AF authority	database routines .SH SYNOPSIS .B "#include
  <AF/AFauth.h>"

  typedef struct xauth {
       unsigned	short family;
       unsigned	short address_length;
       const char     *address;
       unsigned	short number_length;
       const char     *number;
       unsigned	short name_length;
       const char     *name;
       unsigned	short data_length;
       const char     *data;
  } AFauth;

  char *AFauFileName ()

  AFauth *AFauReadAuth (auth_file)
       FILE *auth_file;

  int AFauWriteAuth (auth_file,	auth)
       FILE *auth_file;
       AFauth *auth;

  AFauth *AFauGetAuthByAddr (family,
			     address_length, address,
			     number_length, number)
       unsigned	short family;
       unsigned	short address_length;
       char *address;
       unsigned	short number_length;
       char *number;

  int AFauLockAuth (file_name, retries,	timeout, dead)
       char *file_name;
       int retries;
       int timeout;
       long dead;

  int AFauUnlockAuth (file_name)
       char *file_name;

  AFauDisposeAuth (auth)
       AFauth *auth;


DESCRIPTION

  AFauFileName generates the default authorization file	name by	first check-
  ing the AFauTHROTIY environment variable if set, else	it returns
  $HOME/.AFauthority.  This name is statically allocated and should not	be
  freed.

  AFauReadAuth reads the next entry from auth_file.  The entry is not stati-
  cally	allocated and should be	freed by calling AFauDisposeAuth.


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

  AFauGetAuthByAddr 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 AFauDisposeAuth

  AFauLockAuth does the	work necessary to synchronously	update an authoriza-
  tion file.  First it makes to	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, AFauLockAuth removes it and	the
  associated ``-l'' file.  To prevent possible synchronization troubles	with
  NFS, a dead value of zero forces the files to	be removed.  AFauLockAuth
  makes	retries	attempts to create and link the	file names, pausing timeout
  seconds between each attempt.	 AFauLockAuth 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.


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

  AFauDisposeAuth frees	storage	allocated to hold an authorization entry.

SEE ALSO

COPYRIGHT
  Copyright 1988, Massachusetts	Institute of Technology, 1993, Digital Equip-
  ment Corporation
  See AF(1) for	a full statement of rights and permissions.

AUTHOR
  Keith	Packard, MIT X Consortium