Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


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:

             static 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").

NetBSD 10.99                    January 2, 2022                   NetBSD 10.99