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 39initializes some library internal structures, and tests for the 40presense of AFS in the kernel, none of the other functions should be 41called before 42.Fn k_hasafs 43is called, or if it fails. 44 45.Fn krb_afslog , 46and 47.Fn krb_afslog_uid 48obtains new tokens (and possibly tickets) for the specified 49.Fa cell 50and 51.Fa realm . 52If 53.Fa cell 54is 55.Dv NULL , 56the local cell is used. If 57.Fa realm 58is 59.Dv NULL , 60the 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 63will use the real user-id for the 64.Dv ViceId 65field in the token, 66.Fn krb_afslog_uid 67will 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 86will in 87.Fa cell 88return the cell of a specified file, no more than 89.Fa len 90characters is put in 91.Fa cell . 92 93.Fn k_pioctl 94does a 95.Fn pioctl 96syscall with the specified arguments. This function is equivalent to 97.Fn lpioctl . 98 99.Fn k_setpag 100initializes a new PAG. 101 102.Fn k_unlog 103removes destroys all tokens in the current PAG. 104 105.Sh ENVIRONMENT 106The following environment variable affect the mode of operation of 107.Nm kafs : 108.Bl -tag 109.It Ev AFS_SYSCALL 110Normally, 111.Nm kafs 112will try to figure out the correct system call(s) that are used by AFS 113by itself. If it does not manage to do that, or does it incorrectly, 114you can set this variable to the system call number or list of system 115call numbers that should be used. 116.El 117.Sh RETURN VALUES 118.Fn k_hasafs 119returns 1 if AFS is present in the kernel, 0 otherwise. 120.Fn krb_afslog 121and 122.Fn krb_afslog_uid 123returns 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 , 127and 128.Fn k_unlog 129all return the value of the underlaying system call, 0 on success. 130.Sh EXAMPLES 131The following code from 132.Nm login 133will obtain a new PAG and tokens for the local cell and the cell of 134the users home directory. 135.Bd -literal 136if (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 145If any of these functions (appart from 146.Fn k_hasafs ) 147is called without AFS beeing present in the kernel, the process will 148usually (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 158has no effect under AIX. 159