1.\" $Id: kafs.3,v 1.8 2002/08/28 20:04:31 joda 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 LIBRARY 18AFS cache manager access library (libkafs, -lkafs) 19.Sh SYNOPSIS 20.Fd #include <kafs.h> 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.Ft int 32.Fn krb_afslog "char *cell" "char *realm" 33.Ft int 34.Fn krb_afslog_uid "char *cell" "char *realm" "uid_t uid" 35.\" .Ft krb5_error_code 36.\" .Fn krb5_afslog_uid "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" "uid_t uid" 37.\" .Ft krb5_error_code 38.\" .Fn krb5_afslog "krb5_context context" "krb5_ccache id" "const char *cell" "krb5_const_realm realm" 39.Sh DESCRIPTION 40.Fn k_hasafs 41initializes some library internal structures, and tests for the 42presence of AFS in the kernel, none of the other functions should be 43called before 44.Fn k_hasafs 45is called, or if it fails. 46.Pp 47.Fn krb_afslog , 48and 49.Fn krb_afslog_uid 50obtains new tokens (and possibly tickets) for the specified 51.Fa cell 52and 53.Fa realm . 54If 55.Fa cell 56is 57.Dv NULL , 58the local cell is used. If 59.Fa realm 60is 61.Dv NULL , 62the function tries to guess what realm to use. Unless you have some good knowledge of what cell or realm to use, you should pass 63.Dv NULL . 64.Fn krb_afslog 65will use the real user-id for the 66.Dv ViceId 67field in the token, 68.Fn krb_afslog_uid 69will use 70.Fa uid . 71.Pp 72.\" .Fn krb5_afslog , 73.\" and 74.\" .Fn krb5_afslog_uid 75.\" are the Kerberos 5 equivalents of 76.\" .Fn krb_afslog , 77.\" and 78.\" .Fn krb_afslog_uid . 79.\" The extra arguments are the ubiquitous context, and the cache id where 80.\" to store any obtained tickets. Since AFS servers normally can't handle 81.\" Kerberos 5 tickets directly, these functions will first obtain version 82.\" 5 tickets for the requested cells, and then convert them to version 4 83.\" tickets, that can be stashed in the kernel. To convert tickets the 84.\" .Fn krb524_convert_creds_kdc 85.\" function will be used. 86.\" .Pp 87.Fn k_afs_cell_of_file 88will in 89.Fa cell 90return the cell of a specified file, no more than 91.Fa len 92characters is put in 93.Fa cell . 94.Pp 95.Fn k_pioctl 96does a 97.Fn pioctl 98syscall with the specified arguments. This function is equivalent to 99.Fn lpioctl . 100.Pp 101.Fn k_setpag 102initializes a new PAG. 103.Pp 104.Fn k_unlog 105removes destroys all tokens in the current PAG. 106.Sh RETURN VALUES 107.Fn k_hasafs 108returns 1 if AFS is present in the kernel, 0 otherwise. 109.Fn krb_afslog 110and 111.Fn krb_afslog_uid 112returns 0 on success, or a kerberos error number on failure. 113.Fn k_afs_cell_of_file , 114.Fn k_pioctl , 115.Fn k_setpag , 116and 117.Fn k_unlog 118all return the value of the underlaying system call, 0 on success. 119.Sh ENVIRONMENT 120The following environment variable affect the mode of operation of 121.Nm kafs : 122.Bl -tag -width AFS_SYSCALL 123.It Ev AFS_SYSCALL 124Normally, 125.Nm kafs 126will try to figure out the correct system call(s) that are used by AFS 127by itself. If it does not manage to do that, or does it incorrectly, 128you can set this variable to the system call number or list of system 129call numbers that should be used. 130.El 131.Sh EXAMPLES 132The following code from 133.Nm login 134will obtain a new PAG and tokens for the local cell and the cell of 135the users home directory. 136.Bd -literal 137if (k_hasafs()) { 138 char cell[64]; 139 k_setpag(); 140 if(k_afs_cell_of_file(pwd->pw_dir, cell, sizeof(cell)) == 0) 141 krb_afslog(cell, NULL); 142 krb_afslog(NULL, NULL); 143} 144.Ed 145.Sh ERRORS 146If any of these functions (apart from 147.Fn k_hasafs ) 148is called without AFS beeing present in the kernel, the process will 149usually (depending on the operating system) receive a SIGSYS signal. 150.Sh SEE ALSO 151.Rs 152.%A Transarc Corporation 153.%J AFS-3 Programmer's Reference 154.%T File Server/Cache Manager Interface 155.%D 1991 156.Re 157.Sh BUGS 158.Ev AFS_SYSCALL 159has no effect under AIX. 160