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_afsklog ,
   9 .Nm k_afsklog_uid ,
  10 .Nm k_pioctl ,
  11 .Nm k_unlog ,
  12 .Nm k_setpag ,
  13 .Nm k_afs_cell_of_file
  14 .Nd AFS library
  15 .Sh SYNOPSIS
  16 .Fd #include <kafs.h>
  17 .Ft int
  18 .Fn k_afsklog "char *cell" "char *realm"
  19 .Ft int
  20 .Fn k_afsklog_uid "char *cell" "char *realm" "uid_t uid"
  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 .Sh DESCRIPTION
  32 .Fn k_hasafs
  33 initializes some library internal structures, and tests for the
  34 presense of AFS in the kernel, none of the other functions should be
  35 called before
  36 .Fn k_hasafs
  37 is called, or if it fails.
  38
  39 .Fn k_afsklog ,
  40 and
  41 .Fn k_afsklog_uid
  42 obtains new tokens (and possibly tickets) for the specified
  43 .Fa cell
  44 and
  45 .Fa realm .
  46 If
  47 .Fa cell
  48 is
  49 .Dv NULL ,
  50 the local cell is used. If
  51 .Fa realm
  52 is
  53 .Dv NULL ,
  54 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
  55 .Dv NULL .
  56 .Fn k_afsklog
  57 will use the real user-id for the
  58 .Dv ViceId
  59 field in the token,
  60 .Fn k_afsklog_uid
  61 will use
  62 .Fa uid .
  63
  64 .Fn k_afs_cell_of_file
  65 will in
  66 .Fa cell
  67 return the cell of a specified file, no more than
  68 .Fa len
  69 characters is put in
  70 .Fa cell .
  71
  72 .Fn k_pioctl
  73 does a
  74 .Fn pioctl
  75 syscall with the specified arguments. This function is equivalent to
  76 .Fn lpioctl .
  77
  78 .Fn k_setpag
  79 initializes a new PAG.
  80
  81 .Fn k_unlog
  82 removes destroys all tokens in the current PAG.
  83
  84 .Sh RETURN VALUES
  85 .Fn k_hasafs
  86 returns 1 if AFS is present in the kernel, 0 otherwise.
  87 .Fn k_afsklog
  88 and
  89 .Fn k_afsklog_uid
  90 returns 0 on success, or a kerberos error number on failure.
  91 .Fn k_afs_cell_of_file ,
  92 .Fn k_pioctl ,
  93 .Fn k_setpag ,
  94 and
  95 .Fn k_unlog
  96 all return the value of the underlaying system call, 0 on success.
  97 .Sh EXAMPLES
  98 The following code from
  99 .Nm login
 100 will obtain a new PAG and tokens for the local cell and the cell of
 101 the users home directory.
 102 .Bd -literal
 103 if (k_hasafs()) {
 104         char cell[64];
 105         k_setpag();
 106         if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0)
 107                 k_afsklog(cell, 0);
 108         k_afsklog(0, 0);
 109 }
 110 .Ed
 111 .Sh ERRORS
 112 If any of these functions (appart from
 113 .Fn k_hasafs )
 114 is called without AFS beeing present in the kernel, the process will
 115 usually (depending on the operating system) receive a SIGSYS signal.
 116 .Sh SEE ALSO
 117 .Rs
 118 .%A Transarc Corporation
 119 .%J AFS-3 Programmer's Reference
 120 .%T File Server/Cache Manager Interface
 121 .%D 1991
 122 .Re