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.
— Function: int getpt (void)
The 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 -1 is returned instead. The following
errno conditions are defined for this function:
ENOENT
There are no free master pseudo-terminals available.
This function is a GNU extension.
— Function: int grantpt (int filedes)
The 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 Process Persona), 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 How Change Persona). As a
consequence, installing a signal handler for the SIGCHLD signal
(see Job Control Signals) may interfere with a call to
grantpt.
The normal return value from grantpt is 0; a value of
-1 is returned in case of failure. The following errno
error conditions are defined for this function:
EBADF
The filedes argument is not a valid file descriptor.
EINVAL
The filedes argument is not associated with a master pseudo-terminal
device.
EACCES
The slave pseudo-terminal device corresponding to the master associated
with filedes could not be accessed.
— Function: int unlockpt (int filedes)
The 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 0; a value of
-1 is returned in case of failure. The following errno
error conditions are defined for this function:
EBADF
The filedes argument is not a valid file descriptor.
EINVAL
The filedes argument is not associated with a master pseudo-terminal
device.
— Function: char * ptsname (int filedes)
If the file descriptor filedes is associated with a
master pseudo-terminal device, the 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.
— Function: int ptsname_r (int filedes, char *buf, size_t len)
The 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;
}
Published under the terms of the GNU General Public License