Short term, this is notes on what the interfaces to various libpty functions do....

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@7317 dc483132-0cff-0310-8789-dd5450dbe970

diff --git a/src/util/pty/README b/src/util/pty/README
new file mode 100644 (file)
index 0000000..937e3d4
--- /dev/null
+++ b/src/util/pty/README
@@ -0,0 +1,105 @@
+       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_ets(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.
+
+
+