ptsname

ptsname is a function defined by POSIX that returns the pathname of the slave pseudo-terminal device associated with a given pseudo-terminal master file descriptor. When a program creates a pty pair (for example by using posix_openpt to obtain a master fd), grantpt and unlockpt are typically used to enable access to the slave side, and ptsname can then be used to obtain the path to that slave device, such as /dev/pts/3. The returned string identifies the device name that the process or its child can open to interact with the slave end of the pty.

Usage normally follows the sequence: open a master pty with posix_openpt, call grantpt(fd) and unlockpt(fd), then call ptsname(fd) to obtain the slave’s path. The returned value is a pointer to a static buffer in many implementations and may be overwritten by subsequent calls, so it should be copied if it needs to be preserved.

Variants and portability: The function is part of POSIX and is available on most Unix-like systems. The prototype is typically char *ptsname(int fd), and the required headers can vary by system (often <stdlib.h> or <stdio.h>, sometimes alongside unistd.h). For safer, thread-safe usage, many systems offer ptsname_r, which fills a caller-provided buffer with the slave pathname.

Error handling: If fd does not refer to a valid master pty or the slave name cannot be determined, ptsname returns NULL and sets errno. The reentrant variant ptsname_r returns zero on success and nonzero on failure, leaving errno unchanged accordingly.

In summary, ptsname maps a master pty descriptor to its corresponding slave device path, enabling programs to open and use the slave end of a pseudoterminal.