crypto/heimdal/lib/kafs/kafs.3

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