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