Debian Codegraph @

upstream/debian-unstable/man3/ptsname.3

raw
1 '\" t
2 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
3 .\" This page is in the public domain. - aeb
4 .\" %%%LICENSE_END
5 .\"
6 .TH ptsname 3 2025-10-29 "Linux man-pages 6.18"
7 .SH NAME
8 ptsname, ptsname_r \- get the name of the slave pseudoterminal
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <stdlib.h>
15 .P
16 .BI "char *ptsname(int " fd );
17 .BR "int ptsname_r(" "size_t size;"
18 .BI " int " fd ", char " buf [ size "], size_t " size );
19 .fi
20 .P
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
26 .BR ptsname ():
27 .nf
28 Since glibc 2.24:
29 _XOPEN_SOURCE >= 500
30 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
31 glibc 2.23 and earlier:
32 _XOPEN_SOURCE
33 .fi
34 .P
35 .BR ptsname_r ():
36 .nf
37 _GNU_SOURCE
38 .fi
39 .SH DESCRIPTION
40 The
41 .BR ptsname ()
42 function returns the name of the slave pseudoterminal device
43 corresponding to the master referred to by the file descriptor
44 .IR fd .
45 .P
46 The
47 .BR ptsname_r ()
48 function is the reentrant equivalent of
49 .BR ptsname ().
50 It returns the name of the slave pseudoterminal device as a
51 null-terminated string in the buffer pointed to by
52 .IR buf .
53 The
54 .I size
55 argument specifies the number of bytes available in
56 .IR buf .
57 .SH RETURN VALUE
58 On success,
59 .BR ptsname ()
60 returns a pointer to a string in static storage which will be
61 overwritten by subsequent calls.
62 This pointer must not be freed.
63 On failure, NULL is returned.
64 .P
65 On success,
66 .BR ptsname_r ()
67 returns 0.
68 On failure, an error number is returned to indicate the error.
69 .\" In glibc, the error number is not only returned as the return value
70 .\" but also stored in errno. But this is not true for musl libc.
71 .SH ERRORS
72 .TP
73 .B EINVAL
74 .RB ( ptsname_r ()
75 only)
76 .I buf
77 is NULL.
78 (This error is returned only for
79 .\" glibc commit 8f0a947cf55f3b0c4ebdf06953c57eff67a22fa9
80 glibc 2.25 and earlier.)
81 .TP
82 .B ENOTTY
83 .I fd
84 does not refer to a pseudoterminal master device.
85 .TP
86 .B ERANGE
87 .RB ( ptsname_r ()
88 only)
89 .I buf
90 is too small.
91 .SH ATTRIBUTES
92 For an explanation of the terms used in this section, see
93 .BR attributes (7).
94 .TS
95 allbox;
96 lbx lb lb
97 l l l.
98 Interface Attribute Value
99 T{
100 .na
101 .nh
102 .BR ptsname ()
103 T} Thread safety MT-Unsafe race:ptsname
104 T{
105 .na
106 .nh
107 .BR ptsname_r ()
108 T} Thread safety MT-Safe
109 .TE
110 .SH VERSIONS
111 A version of
112 .BR ptsname_r ()
113 is documented on Tru64, HP-UX, and FreeBSD,
114 but on those implementations,
115 \-1 is returned on error, with
116 .I errno
117 set to indicate the error.
118 Avoid using this function in portable programs.
119 .SH STANDARDS
120 .TP
121 .BR ptsname ():
122 POSIX.1-2008.
123 .TP
124 .BR ptsname_r ():
125 POSIX.1-2024.
126 .SH HISTORY
127 .TP
128 .BR ptsname ():
129 POSIX.1-2001.
130 glibc 2.1.
131 .P
132 .BR ptsname ()
133 is part of the UNIX 98 pseudoterminal support (see
134 .BR pts (4)).
135 .TP
136 .BR ptsname_r ():
137 GNU.
138 .SH SEE ALSO
139 .BR grantpt (3),
140 .BR posix_openpt (3),
141 .BR ttyname (3),
142 .BR unlockpt (3),
143 .BR pts (4),
144 .BR pty (7)