This file is to serve as documentation and usage notes on
libpty until
more formal docs are written.  By that point, it will probably
describe how pty can be broken out of the Kerberos distribution.

void pty_init(void);

	 Initialize error tables.


long pty_getpty ( int *fd, char *slave, int slavelength);
	Find and initialize a clean master pty.  This should open the
pty as fd, and return the name of the slave.  It should return 0 or an
error code.  The slavelength parameter should include the maximum
length allocated for a slave name.  The slave may not be initialized, although any

operating-system specific initialization (for example, unlockpt and
grantpt) may be performed.

long pty_open_slave (/*in */ char * slave, /* out*/ int *fd)

	Initialize the slave side by dissociating the current terminal
and by setting process groups, etc.  In addition, it will initialize
the terminal flags (termios or old BSD) appropriately; the application
may have to do additional customization, but this should sanitize
things.  In addition, the pty will be opened securely, and will become
the controlling terminal.  This procedure will fail unless the process
is running as root.  Ideally, pty_open_slave will be called in a child
process of the process that called pty_getpty.  If an operating system
implements setsid() per the POSIX spec, but does not implement
TIOCNOTTY, this procedure will not be able to insure that the
controlling terminal is established if it is called in the parent
process.  Unfortunately, the parent process must not write to the pty
until the slave side is opened.  Also, the parent process should not
open the slave side through other means unless it is prepared to have
that file descriptor subjected to a vhangup() or revoke() when
pty_open_slave is called in the child.  So, ideally, the parent calls
pty_getpty, forks, waits for the slave to call pty_open_slave, then
continues.  Since this synchronization may be difficult to build in to
existing programs, pty_open_slave makes an effort to function if
called in the parent under operating systems where this is possible.
Currently, I haven't found any operating systems where this isn't
possible.  Also note that pty_open_slave will succeed only once per process.

long pty_open_ctty(int *fd, char *line)

	Attempt to disassociate the current process from its controlling terminal and open line as a new controlling terminal.  No assumption about line being the slave side of a pty is made.

long pty_initialize_slave (int fd)

	Perform the non-security related initializations on the slave
side of a pty.  For example, push the appropriate streams, set termios
structures, etc.  This is included in pty_open_slave.  I am interested
in any suggestions on how to pass information on the state to which
the application wants the terminal initialized.  For example, rlogind
wants a transparent channel, while other programs likely want cooked
mode.  I can't take a termios structure because I may be on a
non-termios system.  Currently, I push the streams, do a bit of
cleanup, but don't really modify the terminal that much. Another
possible goal for this function would be to do enough initialization
that the slave side of the pty can be treated simply as a tty instead
of a pty after this call.


long pty_update_utmp ( int process_type, int pid, char *user, char
*line, char *host, int flags)

	Update the utmp information or return an error.The
process_type is one of the magic types defined in libpty.h.  The flags
are logical combinations of one of the following:

    		PTY_TTYSLOT_USABLE: The tty pointed to by the line
		  parameter is the first tty that would be found by
		  searching stdin then stdout.  In other words,
		  ttyslot() would return the right slot in utmp on
		  systems where ttyslot() is cannonically used.  Note
		  that for inserting utmp entries for new logins, it
		  is not always possible to find the right place if
		  this flag is not given. Thus, for programs like
		  telnetd that set up utmp entries, it is important to
		  be able to set this flag on the initial utmp update.
		  It is expected that this flag may be cleared on
		  update_utmp calls to remove utmp entries.

		PTY_UTMP_USERNAME_VALID: the username field in the
		  utmp entry associated with this line contains the
		  user who (is/was) associated with the line.
		  Regardless of this flag, the utmp file will contain
		  the username specified after this call.  However, if
		  a username is needed by the system for wtmp logout
		  (Solaris 2.1 for example), then the system can fetch
		  the user from the utmp record before doing the wtmp
		  update.  This will only be attempted if the username
		  is a null pointer.  

long pty_cleanup(char *slave, pid_t pid, int update_wtmp)

	Clean up after the slave application has exited.  Close down
the pty, HUPing processes associated with it.  (pid is the pid of the
slave process that may have died, slave is the name of the slave
terminal.)  PID is allowed to be zero if unknown; this may disable
some cleanup operations.  This routine may fork on some systems.  As
such, SIGCHLD may be generated and blocked for some time during the
routine.  In addition, on systems without waitpid() or wait4(), wait()
may be called.