This subsection describes functions for allocating a pseudo-terminal, and for making this pseudo-terminal available for actual use. These functions are declared in the header file `stdlib.h'.
getpt
function returns a new file descriptor for the next
available master pseudo-terminal. The normal return value from
getpt
is a non-negative integer file descriptor. In the case of
an error, a value of @math{-1} is returned instead. The following
errno
conditions are defined for this function:
ENOENT
This function is a GNU extension.
grantpt
function changes the ownership and access permission
of the slave pseudo-terminal device corresponding to the master
pseudo-terminal device associated with the file descriptor
filedes. The owner is set from the real user ID of the calling
process (see section The Persona of a Process), and the group is set to a special
group (typically tty) or from the real group ID of the calling
process. The access permission is set such that the file is both
readable and writable by the owner and only writable by the group.
On some systems this function is implemented by invoking a special
setuid
root program (see section How an Application Can Change Persona). As a
consequence, installing a signal handler for the SIGCHLD
signal
(see section Job Control Signals) may interfere with a call to
grantpt
.
The normal return value from grantpt
is @math{0}; a value of
@math{-1} is returned in case of failure. The following errno
error conditions are defined for this function:
EBADF
ENINVAL
EACCESS
unlockpt
function unlocks the slave pseudo-terminal device
corresponding to the master pseudo-terminal device associated with the
file descriptor filedes. On many systems, the slave can only be
opened after unlocking, so portable applications should always call
unlockpt
before trying to open the slave.
The normal return value from unlockpt
is @math{0}; a value of
@math{-1} is returned in case of failure. The following errno
error conditions are defined for this function:
EBADF
EINVAL
ptsname
function returns a
pointer to a statically-allocated, null-terminated string containing the
file name of the associated slave pseudo-terminal file. This string
might be overwritten by subsequent calls to ptsname
.
ptsname_r
function is similar to the ptsname
function
except that it places its result into the user-specified buffer starting
at buf with length len.
This function is a GNU extension.
Portability Note: On System V derived systems, the file
returned by the ptsname
and ptsname_r
functions may be
STREAMS-based, and therefore require additional processing after opening
before it actually behaves as a pseudo terminal.
Typical usage of these functions is illustrated by the following example:
int open_pty_pair (int *amaster, int *aslave) { int master, slave; char *name; master = getpt (); if (master < 0) return 0; if (grantpt (master) < 0 || unlockpt (master) < 0) goto close_master; name = ptsname (master); if (name == NULL) goto close_master; slave = open (name, O_RDWR); if (slave == -1) goto close_master; if (isastream (slave)) { if (ioctl (slave, I_PUSH, "ptem") < 0 || ioctl (slave, I_PUSH, "ldterm") < 0) goto close_slave; } *amaster = master; *aslave = slave; return 1; close_slave: close (slave); close_master: close (master); return 0; }
Go to the first, previous, next, last section, table of contents.