From: Sam Hartman Date: Mon, 15 Jan 1996 20:37:32 +0000 (+0000) Subject: Short term, this is notes on what the interfaces to various libpty functions do.... X-Git-Tag: krb5-1.0-beta6~617 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=6a43ea4aed5c8834372fa40ce89d7d1ddfa1fe6d;p=krb5.git Short term, this is notes on what the interfaces to various libpty functions do. Long term, I may end up writing something more formal to go into doc. If that happens, it is likely that this README will be removed or replaced with a README explaining how to break libpty out of the Kerberos distribution and get configure to be happy 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 index 000000000..937e3d44a --- /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. + + +