.\" Hey Emacs! This file is -*- nroff -*- source.
.\" This page is in the public domain. - aeb
.\"
.\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS
.\"
.TH PTSNAME 3 "2004-12-17" "PTY Control" "Linux Programmer's Manual"
.SH NAME
ptsname, ptsname_r \- get the name of the slave pseudo-terminal
.SH SYNOPSIS
.nf
.B #define _XOPEN_SOURCE
.br
.B #include <stdlib.h>
.sp
.BI "char *ptsname(int " fd ");"
.sp
.B #define _GNU_SOURCE
.br
.B #include <stdlib.h>
.sp
.BI "char *ptsname_r(int " fd ", char * " buf ", size_t " buflen ");"
.fi
.SH DESCRIPTION
The
.BR ptsname ()
function returns the name of the slave pseudo-terminal (pty) device
corresponding to the master referred to by
.IR fd .

The
.BR ptsname_r ()
function is the reentrant equivalent of
.BR ptsname ().
It returns the name of the slave pseudo-terminal device as a
null-terminated string in the buffer pointed to by
.IR buf .
The
.I buflen
argument specifies the number of bytes available in
.IR buf .
.SH "RETURN VALUE"
On success,
.BR ptsname ()
returns a pointer to a string in static storage which will be
overwritten by subsequent calls.
This pointer must not be freed.
On failure, a NULL pointer is returned.

On success,
.BR ptsname_r ()
returns 0.
On failure, a non-zero value is returned
and
.I errno
is set to indicate the error.
.\" In fact the errno value is also returned as the function
.\" result -- MTK, Dec 04
.SH ERRORS
.TP
.B EINVAL
.RB ( ptsname_r ()
only)
.I buf
is NULL.
.TP
.B ENOTTY
.I fd
does not refer to a pseudo-terminal master device.
.TP
.B ERANGE
.RB ( ptsname_r ()
only)
.I buf
is too small.
.SH "CONFORMING TO"
.BR ptsname ()
is part of the Unix98 pseudo-terminal support (see
.BR pts (4)).
This function is specified in POSIX 1003.1-2001.

.BR pstname_r ()
is a Linux extension.
A version of this function is provided on Tru64 and HP-UX, but
on those implementations, -1 is returned on error, with
.I errno
set to indicate the error.
Avoid using this function in portable programs.
.SH "SEE ALSO"
.BR grantpt (3),
.BR ttyname (3),
.BR pts (4)