| .\" %%%LICENSE_START(PUBLIC_DOMAIN) |
| .\" This page is in the public domain. - aeb |
| .\" %%%LICENSE_END |
| .\" |
| .\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS |
| .\" |
| .TH PTSNAME 3 2020-06-09 "" "Linux Programmer's Manual" |
| .SH NAME |
| ptsname, ptsname_r \- get the name of the terminal corresponding to a pseudoterminal |
| .SH SYNOPSIS |
| .B #include <stdlib.h> |
| .PP |
| .BI "char *ptsname(int " fd ");" |
| .br |
| .BI "int ptsname_r(int " fd ", char *" buf ", size_t " buflen ");" |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .ad l |
| .BR ptsname (): |
| .br |
| .RS 4 |
| Since glibc 2.24: |
| _XOPEN_SOURCE\ >=\ 500 || |
| (_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED) |
| .br |
| Glibc 2.23 and earlier: |
| _XOPEN_SOURCE |
| .RE |
| .PP |
| .BR ptsname_r (): |
| _GNU_SOURCE |
| .ad |
| .SH DESCRIPTION |
| The |
| .BR ptsname () |
| function returns the name of the terminal device |
| corresponding to the pseudoterminal device referred to by the file descriptor |
| .IR fd . |
| .PP |
| The |
| .BR ptsname_r () |
| function is the reentrant equivalent of |
| .BR ptsname (). |
| It returns the name of the 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, NULL is returned. |
| .PP |
| On success, |
| .BR ptsname_r () |
| returns 0. |
| On failure, an error number is returned to indicate the error. |
| .\" In glibc, the error number is not only returned as the return value |
| .\" but also stored in errno. But this is not true for musl libc. |
| .SH ERRORS |
| .TP |
| .B EINVAL |
| .RB ( ptsname_r () |
| only) |
| .I buf |
| is NULL. |
| (This error is returned only for |
| .\" glibc commit 8f0a947cf55f3b0c4ebdf06953c57eff67a22fa9 |
| glibc 2.25 and earlier.) |
| .TP |
| .B ENOTTY |
| .I fd |
| does not refer to a pseudoterminal device. |
| .TP |
| .B ERANGE |
| .RB ( ptsname_r () |
| only) |
| .I buf |
| is too small. |
| .SH VERSIONS |
| .BR ptsname () |
| is provided in glibc since version 2.1. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lb lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR ptsname () |
| T} Thread safety MT-Unsafe race:ptsname |
| T{ |
| .BR ptsname_r () |
| T} Thread safety MT-Safe |
| .TE |
| .SH CONFORMING TO |
| .BR ptsname (): |
| POSIX.1-2001, POSIX.1-2008. |
| .PP |
| .BR ptsname () |
| is part of the UNIX 98 pseudoterminal support (see |
| .BR pts (4)). |
| .PP |
| .BR ptsname_r () |
| is a Linux extension, that is proposed for inclusion |
| .\" FIXME . for later review when Issue 8 is one day released |
| .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 |
| .\" http://austingroupbugs.net/view.php?id=508 |
| in the next major revision of POSIX.1 (Issue 8). |
| 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) |