man3/ptsname.3

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