illumos: 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.