| .\" 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 ptsname_r () |
| is a Linux extension. |
| A version of this function is documented 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 posix_openpt (3), |
| .BR ttyname (3), |
| .BR unlockpt (3), |
| .BR pts (4), |
| .BR pty (7) |