PTSNAME(3)

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

LIBRARY
libc

SYNOPSIS
#include <stdlib.h>
char *
ptsname(int masterfd);
char *
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 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 p1003.1-2001. Its first release was in xpg4.2.