crypto/kerberosIV/man/kafs.3

   1 .\"     $Id: kafs.3,v 1.3 1998/06/30 15:41:52 assar Exp $
   2 .\"
   3 .Dd May 7, 1997
   4 .Os KTH-KRB
   5 .Dt KAFS 3
   6 .Sh NAME
   7 .Nm k_hasafs ,
   8 .Nm k_pioctl ,
   9 .Nm k_unlog ,
  10 .Nm k_setpag ,
  11 .Nm k_afs_cell_of_file ,
  12 .Nm krb_afslog ,
  13 .Nm krb_afslog_uid
  14 .\" .Nm krb5_afslog ,
  15 .\" .Nm krb5_afslog_uid
  16 .Nd AFS library
  17 .Sh SYNOPSIS
  18 .Fd #include <kafs.h>
  19 .Ft int
  20 .Fn k_afs_cell_of_file "const char *path" "char *cell" "int len"
  21 .Ft int
  22 .Fn k_hasafs
  23 .Ft int
  24 .Fn k_pioctl "char *a_path" "int o_opcode" "struct ViceIoctl *a_paramsP" "int a_followSymlinks"
  25 .Ft int
  26 .Fn k_setpag
  27 .Ft int
  28 .Fn k_unlog
  29 .Ft int
  30 .Fn krb_afslog "char *cell" "char *realm"
  31 .Ft int
  32 .Fn krb_afslog_uid "char *cell" "char *realm" "uid_t uid"
  33 .\" .Ft krb5_error_code
  34 .\" .Fn krb5_afslog_uid "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" "uid_t uid"
  35 .\" .Ft krb5_error_code
  36 .\" .Fn krb5_afslog "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm"
  37 .Sh DESCRIPTION
  38 .Fn k_hasafs
  39 initializes some library internal structures, and tests for the
  40 presense of AFS in the kernel, none of the other functions should be
  41 called before
  42 .Fn k_hasafs
  43 is called, or if it fails.
  44 .Pp
  45 .Fn krb_afslog ,
  46 and
  47 .Fn krb_afslog_uid
  48 obtains new tokens (and possibly tickets) for the specified
  49 .Fa cell
  50 and
  51 .Fa realm .
  52 If
  53 .Fa cell
  54 is
  55 .Dv NULL ,
  56 the local cell is used. If
  57 .Fa realm
  58 is
  59 .Dv NULL ,
  60 the function tries to guess what realm to use. Unless you  have some good knowledge of what cell or realm to use, you should pass
  61 .Dv NULL .
  62 .Fn krb_afslog
  63 will use the real user-id for the
  64 .Dv ViceId
  65 field in the token,
  66 .Fn krb_afslog_uid
  67 will use
  68 .Fa uid .
  69 .Pp
  70 .\" .Fn krb5_afslog ,
  71 .\" and
  72 .\" .Fn krb5_afslog_uid
  73 .\" are the Kerberos 5 equivalents of
  74 .\" .Fn krb_afslog ,
  75 .\" and
  76 .\" .Fn krb_afslog_uid .
  77 .\" The extra arguments are the ubiquitous context, and the cache id where
  78 .\" to store any obtained tickets. Since AFS servers normally can't handle
  79 .\" Kerberos 5 tickets directly, these functions will first obtain version
  80 .\" 5 tickets for the requested cells, and then convert them to version 4
  81 .\" tickets, that can be stashed in the kernel. To convert tickets the
  82 .\" .Fn krb524_convert_creds_kdc
  83 .\" function will be used.
  84 .\" .Pp
  85 .Fn k_afs_cell_of_file
  86 will in
  87 .Fa cell
  88 return the cell of a specified file, no more than
  89 .Fa len
  90 characters is put in
  91 .Fa cell .
  92 .Pp
  93 .Fn k_pioctl
  94 does a
  95 .Fn pioctl
  96 syscall with the specified arguments. This function is equivalent to
  97 .Fn lpioctl .
  98 .Pp
  99 .Fn k_setpag
 100 initializes a new PAG.
 101 .Pp
 102 .Fn k_unlog
 103 removes destroys all tokens in the current PAG.
 104 .Sh ENVIRONMENT
 105 The following environment variable affect the mode of operation of
 106 .Nm kafs :
 107 .Bl -tag -width AFS_SYSCALL
 108 .It Ev AFS_SYSCALL
 109 Normally,
 110 .Nm kafs
 111 will try to figure out the correct system call(s) that are used by AFS
 112 by itself.  If it does not manage to do that, or does it incorrectly,
 113 you can set this variable to the system call number or list of system
 114 call numbers that should be used.
 115 .El
 116 .Sh RETURN VALUES
 117 .Fn k_hasafs
 118 returns 1 if AFS is present in the kernel, 0 otherwise.
 119 .Fn krb_afslog
 120 and
 121 .Fn krb_afslog_uid
 122 returns 0 on success, or a kerberos error number on failure.
 123 .Fn k_afs_cell_of_file ,
 124 .Fn k_pioctl ,
 125 .Fn k_setpag ,
 126 and
 127 .Fn k_unlog
 128 all return the value of the underlaying system call, 0 on success.
 129 .Sh EXAMPLES
 130 The following code from
 131 .Nm login
 132 will obtain a new PAG and tokens for the local cell and the cell of
 133 the users home directory.
 134 .Bd -literal
 135 if (k_hasafs()) {
 136         char cell[64];
 137         k_setpag();
 138         if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0)
 139                 krb_afslog(cell, NULL);
 140         krb_afslog(NULL, NULL);
 141 }
 142 .Ed
 143 .Sh ERRORS
 144 If any of these functions (appart from
 145 .Fn k_hasafs )
 146 is called without AFS beeing present in the kernel, the process will
 147 usually (depending on the operating system) receive a SIGSYS signal.
 148 .Sh SEE ALSO
 149 .Rs
 150 .%A Transarc Corporation
 151 .%J AFS-3 Programmer's Reference
 152 .%T File Server/Cache Manager Interface
 153 .%D 1991
 154 .Re
 155 .Sh BUGS
 156 .Ev AFS_SYSCALL
 157 has no effect under AIX.