man3/ttyname.3

   1 '\" t
   2 .\" Copyright (c) 1995 Jim Van Zandt <jrv@vanzandt.mv.com>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" Modified 2001-12-13, Martin Schulze <joey@infodrom.org>
   7 .\" Added ttyname_r, aeb, 2002-07-20
   8 .\"
   9 .TH ttyname 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 ttyname, ttyname_r \- return name of a terminal
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <unistd.h>
  18 .P
  19 .BI "char *ttyname(int " fd );
  20 .BI "int ttyname_r(int " fd ", char " buf [. buflen "], size_t " buflen );
  21 .fi
  22 .SH DESCRIPTION
  23 The function
  24 .BR ttyname ()
  25 returns a pointer to the null-terminated pathname of the terminal device
  26 that is open on the file descriptor \fIfd\fP, or NULL on error
  27 (for example, if \fIfd\fP is not connected to a terminal).
  28 The return value may point to static data, possibly overwritten by the
  29 next call.
  30 The function
  31 .BR ttyname_r ()
  32 stores this pathname in the buffer
  33 .I buf
  34 of length
  35 .IR buflen .
  36 .SH RETURN VALUE
  37 The function
  38 .BR ttyname ()
  39 returns a pointer to a pathname on success.
  40 On error, NULL is returned, and
  41 .I errno
  42 is set to indicate the error.
  43 The function
  44 .BR ttyname_r ()
  45 returns 0 on success, and an error number upon error.
  46 .SH ERRORS
  47 .TP
  48 .B EBADF
  49 Bad file descriptor.
  50 .TP
  51 .\" glibc commit 15e9a4f378c8607c2ae1aa465436af4321db0e23
  52 .B ENODEV
  53 .I fd
  54 refers to a slave pseudoterminal device
  55 but the corresponding pathname could not be found (see NOTES).
  56 .TP
  57 .B ENOTTY
  58 .I fd
  59 does not refer to a terminal device.
  60 .TP
  61 .B ERANGE
  62 .RB ( ttyname_r ())
  63 .I buflen
  64 was too small to allow storing the pathname.
  65 .SH ATTRIBUTES
  66 For an explanation of the terms used in this section, see
  67 .BR attributes (7).
  68 .TS
  69 allbox;
  70 lbx lb lb
  71 l l l.
  72 Interface       Attribute       Value
  73 T{
  74 .na
  75 .nh
  76 .BR ttyname ()
  77 T}      Thread safety   MT-Unsafe race:ttyname
  78 T{
  79 .na
  80 .nh
  81 .BR ttyname_r ()
  82 T}      Thread safety   MT-Safe
  83 .TE
  84 .SH STANDARDS
  85 POSIX.1-2008.
  86 .SH HISTORY
  87 POSIX.1-2001, 4.2BSD.
  88 .SH NOTES
  89 A process that keeps a file descriptor that refers to a
  90 .BR pts (4)
  91 device open when switching to another mount namespace that uses a different
  92 .I /dev/ptmx
  93 instance may still accidentally find that a device path of the same name
  94 for that file descriptor exists.
  95 However, this device path refers to a different device and thus
  96 can't be used to access the device that the file descriptor refers to.
  97 Calling
  98 .BR ttyname ()
  99 or
 100 .BR ttyname_r ()
 101 on the file descriptor in the new mount namespace will cause these
 102 functions to return NULL and set
 103 .I errno
 104 to
 105 .BR ENODEV .
 106 .SH SEE ALSO
 107 .BR tty (1),
 108 .BR fstat (2),
 109 .BR ctermid (3),
 110 .BR isatty (3),
 111 .BR pts (4)