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 RETURN VALUES
 106 .Fn k_hasafs
 107 returns 1 if AFS is present in the kernel, 0 otherwise.
 108 .Fn krb_afslog
 109 and
 110 .Fn krb_afslog_uid
 111 returns 0 on success, or a kerberos error number on failure.
 112 .Fn k_afs_cell_of_file ,
 113 .Fn k_pioctl ,
 114 .Fn k_setpag ,
 115 and
 116 .Fn k_unlog
 117 all return the value of the underlaying system call, 0 on success.
 118 .Sh EXAMPLES
 119 The following code from
 120 .Nm login
 121 will obtain a new PAG and tokens for the local cell and the cell of
 122 the users home directory.
 123 .Bd -literal
 124 if (k_hasafs()) {
 125         char cell[64];
 126         k_setpag();
 127         if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0)
 128                 krb_afslog(cell, NULL);
 129         krb_afslog(NULL, NULL);
 130 }
 131 .Ed
 132 .Sh ERRORS
 133 If any of these functions (appart from
 134 .Fn k_hasafs )
 135 is called without AFS beeing present in the kernel, the process will
 136 usually (depending on the operating system) receive a SIGSYS signal.
 137 .Sh SEE ALSO
 138 .Rs
 139 .%A Transarc Corporation
 140 .%J AFS-3 Programmer's Reference
 141 .%T File Server/Cache Manager Interface
 142 .%D 1991
 143 .Re