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);
char *
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 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:
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”).