Tribblix: manual page: ptsname.3c

PTSNAME(3C) Standard C Library Functions PTSNAME(3C)

NAME

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

SYNOPSIS

#include <stdlib.h>

char *
ptsname(int fildes);

int
ptsname_r(int fildes, char *name, size_t namelen);

DESCRIPTION

The ptsname() function returns the name of the pseudo-terminal
subsidiary device associated with a pseudo-terminal manager device.
The fildes argument is a file descriptor returned from a successful
open of the pseudo-terminal manager device; e.g., by calling
posix_openpt(3C) or by performing an open(2) of the ptm(4D) device.

The ptsname() function returns a pointer to a string containing the
null-terminated path name of the subsidiary device. This string is of
the form /dev/pts/N, where N is a non-negative integer. Callers should
generally assume that a subsequent call to ptsname() will overwrite the
returned buffer. POSIX does not require that the interface be thread-
safe. While a per-thread buffer is currently being used, that should
not be relied upon by portable applications and is not a system
guarantee.

The ptsname_r() function behaves similarly to the ptsname() function,
but rather than use a thread-specific buffer, stores the name of the
pseudo-terminal subsidiary device of fildes in name. The size of name
is indicated by namelen. If the buffer is not large enough, then the
function will fail with ERANGE. The name's length will not exceed
{TTY_NAME_MAX}, which can be determined at runtime by calling
sysconf(3C) with the name _SC_TTY_NAME_MAX.

RETURN VALUES

Upon successful completion, the ptsname() function returns a pointer to
a string which is the name of the pseudo-terminal subsidiary device.
This value points to a static data area that is overwritten by each
call to ptsname() by the same thread. Otherwise, NULL is returned and
errno is set to indicate the error that occurred.

Upon successful completion, the ptsname_r() function will return 0 and
name will be filled in with the subsidiary device's name. Otherwise,
an error number will be returned.

ERRORS

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

EBADF The file descriptor, fildes, does not refer to a
valid file descriptor.

EINVAL The file descriptor, fildes, does not refer to a
manager pseudo-terminal device.

For the ptsname_r() function, name is a NULL
pointer.

ENOTTY The file descriptor, fildes, does not refer to a
manager pseudo-terminal device.

ERANGE For the ptsname_r() function, the buffer name 's
size as indicated by namelen was too small to hold
the actual subsidiary device's name.

INTERFACE STABILITY

Committed

MT LEVEL

The ptsname() function is Safe.

The ptsname_r() function is MT-Safe.