NAME

ptsname, ptsname_r — get name of the subsidiary pseudo-terminal device

SYNOPSIS

[XSI] #include <stdlib.h>

char *ptsname(int fildes);
int ptsname_r(int fildes, char *name, size_t namesize);

DESCRIPTION

The ptsname() function shall return the name of the subsidiary pseudo-terminal device associated with a manager pseudo-terminal device. The fildes argument is a file descriptor that refers to the manager device. The ptsname() function shall return a pointer to a string containing the pathname of the corresponding subsidiary device.

The ptsname() function need not be thread-safe.

The ptsname_r() function shall store the name of the subsidiary pseudo-terminal device corresponding to fildes in the character array referenced by name. The array is namesize characters long and should have space for the name and the terminating null character. The maximum length of the terminal name shall be {TTY_NAME_MAX}.

RETURN VALUE

Upon successful completion, ptsname() shall return a pointer to a string which is the name of the pseudo-terminal subsidiary device. Upon failure, ptsname() shall return a null pointer and may set errno. This could occur if fildes is an invalid file descriptor or if the subsidiary device name does not exist in the file system.

The application shall not modify the string returned. The returned pointer might be invalidated or the string content might be overwritten by a subsequent call to ptsname(). The returned pointer and the string content might also be invalidated if the calling thread is terminated.

If successful, the ptsname_r() function shall return zero. Otherwise, an error number shall be returned to indicate the error.

ERRORS

The ptsname_r() function shall fail if:

[EBADF]

The fildes argument is not a valid file descriptor.

[EINVAL]

The name argument is a null pointer.

[ERANGE]

The value of namesize is smaller than the length of the string to be returned including the terminating null character.

The ptsname() function may fail if:

[EBADF]

The fildes argument is not a valid file descriptor.

The ptsname() and ptsname_r() functions may fail if:

[EINVAL] or [ENOTTY]

The file associated with the fildes argument is not a manager pseudo-terminal device.

EXAMPLES

None.

APPLICATION USAGE

None.

RATIONALE

The ptsname_r() function is required to make it possible for a multi-threaded program to safely determine the name of a subsidiary device. Although the name of the device is constrained by {TTY_NAME_MAX}, this value might not be a compile-time constant, so an application can rely on repeated calls with successively larger buffers until the result is no longer [ERANGE] as an alternative for properly sizing the buffer.

Historically, some versions of ptsname() did not set errno even when returning a null pointer. However, ptsname_r() is required to either populate the buffer with a valid name or return an error value.

See also the RATIONALE section for posix_openpt.

FUTURE DIRECTIONS

None.

SEE ALSO

grantpt, open, posix_openpt, ttyname, unlockpt

XBD <stdlib.h>

CHANGE HISTORY

First released in Issue 4, Version 2.

Issue 5

Moved from X/OPEN UNIX extension to BASE.

A note indicating that this function need not be reentrant is added to the DESCRIPTION.

Issue 7

Austin Group Interpretation 1003.1-2001 #156 is applied.

POSIX.1-2008, Technical Corrigendum 1, XSH/TC1-2008/0468 [75] and XSH/TC1-2008/0469 [96] are applied.

POSIX.1-2008, Technical Corrigendum 2, XSH/TC2-2008/0298 [503], XSH/TC2-2008/0299 [656], and XSH/TC2-2008/0300 [503] are applied.

Issue 8

Austin Group Defect 508 is applied, adding the ptsname_r() function.

Austin Group Defect 1466 is applied, changing the terminology used for pseudo-terminal devices.