PTSNAME(3)

PTSNAME(3) | Library Functions Manual | PTSNAME(3)

# NAME

`ptsname`, `ptsname_r` —
get the pathname of the slave pseudo-terminal device

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <stdlib.h>`

char *
`ptsname`(int masterfd);

int
`ptsname_r`(int masterfd, char *buf, size_t buflen);

# DESCRIPTION

The `ptsname`() function returns the pathname of the slave pseudo-terminal device that corresponds to the master pseudo-terminal device associated with masterfd. The `ptsname`() function is not reentrant or thread-safe.

The `ptsname_r`() function places the pathname of the slave pseudo-terminal device that corresponds to the master pseudo-terminal device associated with masterfd int the buf argument copying up to buflen characters. The buf is always `NUL` terminated.

# RETURN VALUES

If successful, `ptsname`() returns a pointer to a nul-terminated string containing the pathname of the slave pseudo-terminal device. If an error occurs `ptsname`() will return `NULL` and errno is set to indicate the error.

If successful, `ptsname_r`() places a nul-terminated string containing the pathname of the slave pseudo-terminal device in buf and returns `0`. If an error occurs `ptsname_r`() will return an error number indicating what went wrong.

# ERRORS

The `ptsname`() and `ptsname_r`() functions will fail if:

[`EACCESS`]
  the corresponding pseudo-terminal device could not be accessed.
[`EBADF`]
  masterfd is not a valid descriptor.
[`EINVAL`]
  masterfd is not associated with a master pseudo-terminal device.

In addition the `ptsname_r`() function will return:

[`EINVAL`]
  the buf argument is `NULL`.
[`ERANGE`]
  the name of the pseudo-terminal is longer than bufsiz characters plus the terminating `NUL`.

# NOTES

The error returns of `ptsname`() are a NetBSD extension. The `ptsname`() function is equivalent to:

    	struct ptmget pm;
    	return ioctl(masterfd, TIOCPTSNAME, &pm) == -1 ? NULL : pm.sn;

Both the `ptsname`() and `ptsname_r`() functions will also return the name of the slave pseudo-terminal if a file descriptor to the slave pseudo-terminal is passed to masterfd.

This is a convenient extension because it allows one to use the file descriptor obtained by open(2) /dev/tty to obtain the name of the pseudo-terminal for the current process.

# SEE ALSO

ioctl(2), open(2), grantpt(3), posix_openpt(3), unlockpt(3)

# STANDARDS

The `ptsname`() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”). Its first release was in X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”).

February 7, 2018 | NetBSD 9.5