From 4b01996188fb12c1c0165722b63a7c0cc84a6acb Mon Sep 17 00:00:00 2001
From: CSRG <csrg@ucbvax.Berkeley.EDU>
Date: Thu, 17 Jun 1993 03:11:03 -0800
Subject: [PATCH] BSD 4_4_Lite1 development Work on file
 usr/src/kerberosIV/man/tf_util.3

Synthesized-from: CSRG/cd2/4.4BSD-Lite1
---
 usr/src/kerberosIV/man/tf_util.3 | 152 +++++++++++++++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 usr/src/kerberosIV/man/tf_util.3

diff --git a/usr/src/kerberosIV/man/tf_util.3 b/usr/src/kerberosIV/man/tf_util.3
new file mode 100644
index 0000000000..f41e113410
--- /dev/null
+++ b/usr/src/kerberosIV/man/tf_util.3
@@ -0,0 +1,152 @@
+.\" $Source: /usr/src/kerberosIV/man/RCS/tf_util.3,v $
+.\" $Author: kfall $
+.\" $Header: /usr/src/kerberosIV/man/RCS/tf_util.3,v 4.3 90/06/25 21:12:43 kfall Exp $
+.\" Copyright 1989 by the Massachusetts Institute of Technology.
+.\"
+.\" For copying and distribution information,
+.\" please see the file <mit-copyright.h>.
+.\"
+.TH TF_UTIL 3 "Kerberos Version 4.0" "MIT Project Athena"
+.SH NAME
+tf_init, tf_get_pname, tf_get_pinst, tf_get_cred, tf_close \-
+routines for manipulating a Kerberos ticket file
+.SH SYNOPSIS
+.nf
+.nj
+.ft B
+#include <kerberosIV/krb.h>
+.PP
+.ft B
+extern char *krb_err_txt[];
+.PP
+.ft B
+tf_init(tf_name, rw)
+char *tf_name;
+int rw;
+.PP
+.ft B
+tf_get_pname(pname)
+char *pname;
+.PP
+.ft B
+tf_get_pinst(pinst)
+char *pinst;
+.PP
+.ft B
+tf_get_cred(c)
+CREDENTIALS *c;
+.PP
+.ft B
+tf_close()
+.PP
+.fi
+.SH DESCRIPTION
+This group of routines are provided to manipulate the Kerberos tickets
+file.  A ticket file has the following format:
+.nf
+.in +4
+.sp
+principal's name          (null-terminated string)
+principal's instance      (null-terminated string)
+CREDENTIAL_1
+CREDENTIAL_2
+  ...
+CREDENTIAL_n
+EOF
+.sp
+.in -4
+.LP
+Where "CREDENTIAL_x" consists of the following fixed-length
+fields from the CREDENTIALS structure (defined in <kerberosIV/krb.h>):
+.nf
+.sp
+.in +4
+	char		service[ANAME_SZ]
+	char		instance[INST_SZ]
+	char		realm[REALM_SZ]
+	des_cblock	session
+	int		lifetime
+	int		kvno
+	KTEXT_ST	ticket_st
+	long		issue_date
+.in -4
+.sp
+.fi
+.PP
+.I tf_init
+must be called before the other ticket file
+routines.
+It takes the name of the ticket file to use,
+and a read/write flag as arguments.
+It tries to open the ticket file, checks the mode and if
+everything is okay, locks the file.  If it's opened for
+reading, the lock is shared.  If it's opened for writing,
+the lock is exclusive.
+KSUCCESS is returned if all went well, otherwise one of the
+following:
+.nf
+.sp
+NO_TKT_FIL	- file wasn't there
+TKT_FIL_ACC	- file was in wrong mode, etc.
+TKT_FIL_LCK	- couldn't lock the file, even after a retry
+.sp
+.fi
+.PP
+The
+.I tf_get_pname
+reads the principal's name from a ticket file.
+It should only be called after tf_init has been called.  The
+principal's name is filled into the 
+.I pname
+parameter.  If all goes
+well, KSUCCESS is returned.
+If tf_init wasn't called, TKT_FIL_INI
+is returned.
+If the principal's name was null, or EOF was encountered, or the
+name was longer than ANAME_SZ, TKT_FIL_FMT is returned.
+.PP
+The
+.I tf_get_pinst
+reads the principal's instance from a ticket file.
+It should only be called after tf_init and tf_get_pname
+have been called.
+The principal's instance is filled into the 
+.I pinst
+parameter.
+If all goes
+well, KSUCCESS is returned.
+If tf_init wasn't called, TKT_FIL_INI
+is returned.
+If EOF was encountered, or the
+name was longer than INST_SZ, TKT_FIL_FMT is returned.
+Note that, unlike the principal name, the instance name may be null.
+.PP
+The
+.I tf_get_cred
+routine reads a CREDENTIALS record from a ticket file and
+fills in the given structure.
+It should only be called after
+tf_init, tf_get_pname, and tf_get_pinst have been called.
+If all goes well, KSUCCESS is returned.  Possible error codes
+are:
+.nf
+.sp
+TKT_FIL_INI	- tf_init wasn't called first
+TKT_FIL_FMT	- bad format
+EOF		- end of file encountered
+.sp
+.fi
+.PP
+.I tf_close
+closes the ticket file and releases the lock on it.
+.SH "SEE ALSO"
+krb(3)
+.SH DIAGNOSTICS
+.SH BUGS
+The ticket file routines have to be called in a certain order.
+.SH AUTHORS
+Jennifer Steiner, MIT Project Athena
+.br
+Bill Bryant, MIT Project Athena
+.SH RESTRICTIONS
+Copyright 1987 Massachusetts Institute of Technology
-- 
2.20.1