lib/kafs/kafs.3

   1 .\"     $Id$
   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
  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
  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
  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
  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
  99 .Fn k_setpag
 100 initializes a new PAG.
 101
 102 .Fn k_unlog
 103 removes destroys all tokens in the current PAG.
 104
 105 .Sh ENVIRONMENT
 106 The following environment variable affect the mode of operation of
 107 .Nm kafs :
 108 .Bl -tag
 109 .It Ev AFS_SYSCALL
 110 Normally,
 111 .Nm kafs
 112 will try to figure out the correct system call(s) that are used by AFS
 113 by itself.  If it does not manage to do that, or does it incorrectly,
 114 you can set this variable to the system call number or list of system
 115 call numbers that should be used.
 116 .El
 117 .Sh RETURN VALUES
 118 .Fn k_hasafs
 119 returns 1 if AFS is present in the kernel, 0 otherwise.
 120 .Fn krb_afslog
 121 and
 122 .Fn krb_afslog_uid
 123 returns 0 on success, or a kerberos error number on failure.
 124 .Fn k_afs_cell_of_file ,
 125 .Fn k_pioctl ,
 126 .Fn k_setpag ,
 127 and
 128 .Fn k_unlog
 129 all return the value of the underlaying system call, 0 on success.
 130 .Sh EXAMPLES
 131 The following code from
 132 .Nm login
 133 will obtain a new PAG and tokens for the local cell and the cell of
 134 the users home directory.
 135 .Bd -literal
 136 if (k_hasafs()) {
 137         char cell[64];
 138         k_setpag();
 139         if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0)
 140                 krb_afslog(cell, NULL);
 141         krb_afslog(NULL, NULL);
 142 }
 143 .Ed
 144 .Sh ERRORS
 145 If any of these functions (appart from
 146 .Fn k_hasafs )
 147 is called without AFS beeing present in the kernel, the process will
 148 usually (depending on the operating system) receive a SIGSYS signal.
 149 .Sh SEE ALSO
 150 .Rs
 151 .%A Transarc Corporation
 152 .%J AFS-3 Programmer's Reference
 153 .%T File Server/Cache Manager Interface
 154 .%D 1991
 155 .Re
 156 .Sh BUGS
 157 .Ev AFS_SYSCALL
 158 has no effect under AIX.