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.
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.