OPENPTY(3)

OPENPTY(3) | Library Functions Manual | OPENPTY(3)

# NAME

`openpty`, `login_tty`, `forkpty` —
tty utility functions

# LIBRARY

System Utilities Library (libutil, -lutil)

# SYNOPSIS

`#include <util.h>`

int
`openpty`(int *amaster, int *aslave, char *name, struct termios *termp, struct winsize *winp);

int
`login_tty`(int fd);

pid_t
`forkpty`(int *amaster, char *name, struct termios *termp, struct winsize *winp);

# DESCRIPTION

The `openpty`(), `login_tty`(), and `forkpty`() functions perform manipulations on ttys and pseudo-ttys.

The `openpty`() function finds an available pseudo-tty and returns file descriptors for the master and slave in amaster and aslave. If name is non-null, the filename of the slave is returned in name. The length of name is limited to `PATH_MAX` as any other regular path name, so a buffer of this size should be used. If termp is non-null, the terminal parameters of the slave will be set to the values in termp. If winp is non-null, the window size of the slave will be set to the values in winp.

The `login_tty`() function prepares for a login on the tty fd (which may be a real tty device, or the slave of a pseudo-tty as returned by `openpty`()) by creating a new session, making fd the controlling terminal for the current process, setting fd to be the standard input, output, and error streams of the current process, and closing fd.

The `forkpty`() function combines `openpty`(), `fork`(), and `login_tty`() to create a new process operating in a pseudo-tty. The file descriptor of the master side of the pseudo-tty is returned (to the parent process only) in amaster. The filename of the slave is returned (to both the parent and child processes) in name if name is non-null. The termp and winp parameters, if non-null, will determine the terminal attributes and window size of the slave side of the pseudo-tty.

# RETURN VALUES

If a call to `openpty`(), `login_tty`(), or `forkpty`() is not successful, -1 is returned and errno is set to indicate the error. Otherwise, `openpty`(), `login_tty`(), and the child process of `forkpty`() return 0, and the parent process of `forkpty`() returns the process ID of the child process.

# FILES

/dev/[pt]ty[p-zP-T][0-9a-zA-Z]

# ERRORS

`openpty`() will fail if:

[`ENOENT`]
  There are no available ttys.
[`EPERM`]
  The caller was not the superuser and the ptm(4) device is missing or not configured.

`login_tty`() will fail if `ioctl`() fails to set fd to the controlling terminal of the current process. `forkpty`() will fail if either `openpty`() or `fork`() fails.

# SEE ALSO

fork(2)

July 27, 2012 | NetBSD 9.5