pty(3)

NAME

openpty, forkpty - auxiliary functions to obtain a pseudo

terminal

LIBRARY

System Utilities Library (libutil, -lutil)

SYNOPSIS

#include <sys/types.h>
#include <sys/ioctl.h>
#include <termios.h>
#include <libutil.h>
int
openpty(int   *amaster,  int  *aslave,  char  *name,  struct
termios *termp,
        struct winsize *winp);
int
forkpty(int *amaster, char *name, struct termios *termp,
        struct winsize *winp);

DESCRIPTION

The function openpty() attempts to obtain the next available

pseudo-terminal from the system (see pty(4)). If it successfully

finds one, it
subsequently tries to change the ownership of the slave de

vice to the
real UID of the current process, the group membership to the

group
``tty'' (if such a group exists in the system), the access

permissions
for reading and writing by the owner, and for writing by the

group, and
to invalidate any current use of the line by calling re

voke(2).

If the argument name is not NULL, openpty() copies the path

name of the
slave pty to this area. The caller is responsible for allo

cating the
required space in this array.

If the arguments termp or winp are not NULL, openpty() ini

tializes the
termios and window size settings from the structures these

arguments
point to, respectively.

Upon return, the open file descriptors for the master and

slave side of
the pty are returned in the locations pointed to by amaster

and aslave,
respectively.

The forkpty() function first calls openpty() to obtain the

next available
pseudo-terminal from the system. Upon success, it forks off

a new process. In the child process, it closes the descriptor for

the master side
of the pty, and calls login_tty(3) for the slave pty. In

the parent process, it closes the descriptor for the slave side of the

pty. The arguments amaster, name, termp, and winp have the same meaning

as described
for openpty().

RETURN VALUES

The openpty() function returns 0 on success, or -1 on fail

ure.

The forkpty() function returns -1 on failure, 0 in the slave

process, and
the process ID of the slave process in the parent process.

ERRORS

On failure, openpty() will set the global variable errno to

ENOENT.

In addition to this, forkpty() may set it to any value as

described for
fork(2).

SEE ALSO

chmod(2), chown(2), fork(2), getuid(2), open(2), revoke(2),

login_tty(3),
pty(4), termios(4), group(5)

BUGS

The calling process must have an effective UID of super-user

in order to
perform all the intended actions. No notification will oc

cur if
openpty() or forkpty() failed to proceed with one of the de

scribed steps,
as long as they could at least allocate the pty at all (and

create the
new process in the case of forkpty()).

BSD December 29, 1996

BSD