June 17, 2004 OPENPTY 3

### NAME

openpty, login_tty, forkpty - tty utility functions

### LIBRARY

System Utilities Library (libutil, -lutil)

### SYNOPSIS

```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`. 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 in ```amaster`, and the filename of the slave in ```name` if it 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)