1
This file is to serve as documentation and usage notes on
3
more formal docs are written. By that point, it will probably
4
describe how pty can be broken out of the Kerberos distribution.
8
Initialize error tables.
11
long pty_getpty ( int *fd, char *slave, int slavelength);
12
Find and initialize a clean master pty. This should open the
13
pty as fd, and return the name of the slave. It should return 0 or an
14
error code. The slavelength parameter should include the maximum
15
length allocated for a slave name. The slave may not be initialized, although any
17
operating-system specific initialization (for example, unlockpt and
18
grantpt) may be performed.
20
long pty_open_slave (/*in */ char * slave, /* out*/ int *fd)
22
Initialize the slave side by dissociating the current terminal
23
and by setting process groups, etc. In addition, it will initialize
24
the terminal flags (termios or old BSD) appropriately; the application
25
may have to do additional customization, but this should sanitize
26
things. In addition, the pty will be opened securely, and will become
27
the controlling terminal. This procedure will fail unless the process
28
is running as root. Ideally, pty_open_slave will be called in a child
29
process of the process that called pty_getpty. If an operating system
30
implements setsid() per the POSIX spec, but does not implement
31
TIOCNOTTY, this procedure will not be able to insure that the
32
controlling terminal is established if it is called in the parent
33
process. Unfortunately, the parent process must not write to the pty
34
until the slave side is opened. Also, the parent process should not
35
open the slave side through other means unless it is prepared to have
36
that file descriptor subjected to a vhangup() or revoke() when
37
pty_open_slave is called in the child. So, ideally, the parent calls
38
pty_getpty, forks, waits for the slave to call pty_open_slave, then
39
continues. Since this synchronization may be difficult to build in to
40
existing programs, pty_open_slave makes an effort to function if
41
called in the parent under operating systems where this is possible.
42
Currently, I haven't found any operating systems where this isn't
43
possible. Also note that pty_open_slave will succeed only once per process.
45
long pty_open_ctty(int *fd, char *line)
47
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.
49
long pty_initialize_slave (int fd)
51
Perform the non-security related initializations on the slave
52
side of a pty. For example, push the appropriate streams, set termios
53
structures, etc. This is included in pty_open_slave. I am interested
54
in any suggestions on how to pass information on the state to which
55
the application wants the terminal initialized. For example, rlogind
56
wants a transparent channel, while other programs likely want cooked
57
mode. I can't take a termios structure because I may be on a
58
non-termios system. Currently, I push the streams, do a bit of
59
cleanup, but don't really modify the terminal that much. Another
60
possible goal for this function would be to do enough initialization
61
that the slave side of the pty can be treated simply as a tty instead
62
of a pty after this call.
65
long pty_update_utmp ( int process_type, int pid, char *user, char
66
*line, char *host, int flags)
68
Update the utmp information or return an error.The
69
process_type is one of the magic types defined in libpty.h. The flags
70
are logical combinations of one of the following:
72
PTY_TTYSLOT_USABLE: The tty pointed to by the line
73
parameter is the first tty that would be found by
74
searching stdin then stdout. In other words,
75
ttyslot() would return the right slot in utmp on
76
systems where ttyslot() is cannonically used. Note
77
that for inserting utmp entries for new logins, it
78
is not always possible to find the right place if
79
this flag is not given. Thus, for programs like
80
telnetd that set up utmp entries, it is important to
81
be able to set this flag on the initial utmp update.
82
It is expected that this flag may be cleared on
83
update_utmp calls to remove utmp entries.
85
PTY_UTMP_USERNAME_VALID: the username field in the
86
utmp entry associated with this line contains the
87
user who (is/was) associated with the line.
88
Regardless of this flag, the utmp file will contain
89
the username specified after this call. However, if
90
a username is needed by the system for wtmp logout
91
(Solaris 2.1 for example), then the system can fetch
92
the user from the utmp record before doing the wtmp
93
update. This will only be attempted if the username
96
long pty_cleanup(char *slave, pid_t pid, int update_wtmp)
98
Clean up after the slave application has exited. Close down
99
the pty, HUPing processes associated with it. (pid is the pid of the
100
slave process that may have died, slave is the name of the slave
101
terminal.) PID is allowed to be zero if unknown; this may disable
102
some cleanup operations. This routine may fork on some systems. As
103
such, SIGCHLD may be generated and blocked for some time during the
104
routine. In addition, on systems without waitpid() or wait4(), wait()
added
removed
src/appl/libpty/README
