Next: Pseudo-Terminal Pairs, Up: Pseudo-Terminals
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.
The
getptfunction returns a new file descriptor for the next available master pseudo-terminal. The normal return value fromgetptis a non-negative integer file descriptor. In the case of an error, a value of -1 is returned instead. The followingerrnoconditions are defined for this function:
ENOENT- There are no free master pseudo-terminals available.
This function is a GNU extension.
The
grantptfunction 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
setuidroot program (see How Change Persona). As a consequence, installing a signal handler for theSIGCHLDsignal (see Job Control Signals) may interfere with a call tograntpt.The normal return value from
grantptis 0; a value of -1 is returned in case of failure. The followingerrnoerror 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.
The
unlockptfunction 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 callunlockptbefore trying to open the slave.The normal return value from
unlockptis 0; a value of -1 is returned in case of failure. The followingerrnoerror 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.
If the file descriptor filedes is associated with a master pseudo-terminal device, the
ptsnamefunction 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 toptsname.
The
ptsname_rfunction is similar to theptsnamefunction 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;
}