man3/ptsname.3

   1 .\" %%%LICENSE_START(PUBLIC_DOMAIN)
   2 .\" This page is in the public domain. - aeb
   3 .\" %%%LICENSE_END
   4 .\"
   5 .\" 2004-12-17, mtk, added description of ptsname_r() + ERRORS
   6 .\"
   7 .TH PTSNAME 3 2021-03-22 "Linux man-pages (unreleased)"
   8 .SH NAME
   9 ptsname, ptsname_r \- get the name of the slave pseudoterminal
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <stdlib.h>
  16 .PP
  17 .BI "char *ptsname(int " fd ");"
  18 .BI "int ptsname_r(int " fd ", char *" buf ", size_t " buflen ");"
  19 .fi
  20 .PP
  21 .RS -4
  22 Feature Test Macro Requirements for glibc (see
  23 .BR feature_test_macros (7)):
  24 .RE
  25 .PP
  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 .PP
  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 .PP
  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 buflen
  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 .PP
  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 VERSIONS
  92 .BR ptsname ()
  93 is provided in glibc since version 2.1.
  94 .SH ATTRIBUTES
  95 For an explanation of the terms used in this section, see
  96 .BR attributes (7).
  97 .ad l
  98 .nh
  99 .TS
 100 allbox;
 101 lbx lb lb
 102 l l l.
 103 Interface       Attribute       Value
 104 T{
 105 .BR ptsname ()
 106 T}      Thread safety   MT-Unsafe race:ptsname
 107 T{
 108 .BR ptsname_r ()
 109 T}      Thread safety   MT-Safe
 110 .TE
 111 .hy
 112 .ad
 113 .sp 1
 114 .SH STANDARDS
 115 .TP
 116 .BR ptsname ():
 117 POSIX.1-2001, POSIX.1-2008.
 118 .PP
 119 .BR ptsname ()
 120 is part of the UNIX 98 pseudoterminal support (see
 121 .BR pts (4)).
 122 .PP
 123 .BR ptsname_r ()
 124 is a Linux extension, that is proposed for inclusion
 125 .\" FIXME . for later review when Issue 8 is one day released
 126 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
 127 .\" http://austingroupbugs.net/view.php?id=508
 128 in the next major revision of POSIX.1 (Issue 8).
 129 A version of this function is documented on Tru64 and HP-UX, but
 130 on those implementations, \-1 is returned on error, with
 131 .I errno
 132 set to indicate the error.
 133 Avoid using this function in portable programs.
 134 .SH SEE ALSO
 135 .BR grantpt (3),
 136 .BR posix_openpt (3),
 137 .BR ttyname (3),
 138 .BR unlockpt (3),
 139 .BR pts (4),
 140 .BR pty (7)