lib/libc/gen/ttyname.3

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)ttyname.3   8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD: src/lib/libc/gen/ttyname.3,v 1.14 2007/01/09 00:27:55 imp Exp $
  30 .\" $DragonFly: src/lib/libc/gen/ttyname.3,v 1.3 2005/11/19 22:32:53 swildner Exp $
  31 .\"
  32 .Dd March 22, 2009
  33 .Dt TTYNAME 3
  34 .Os
  35 .Sh NAME
  36 .Nm ttyname ,
  37 .Nm ttyname_r ,
  38 .Nm isatty ,
  39 .Nm ttyslot
  40 .Nd get name of associated terminal (tty) from file descriptor
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft char *
  46 .Fn ttyname "int fd"
  47 .Ft int
  48 .Fn ttyname_r "int fd" "char *buf" "size_t len"
  49 .Ft int
  50 .Fn isatty "int fd"
  51 .Ft int
  52 .Fn ttyslot void
  53 .Sh DESCRIPTION
  54 These functions operate on the system file descriptors for terminal
  55 type devices.
  56 These descriptors are not related to the standard
  57 .Tn I/O
  58 .Dv FILE
  59 typedef, but refer to the special device files found in
  60 .Pa /dev
  61 and named
  62 .Pa /dev/tty Ns Ar xx
  63 and for which an entry exists
  64 in the initialization file
  65 .Pa /etc/ttys .
  66 (See
  67 .Xr ttys 5 . )
  68 .Pp
  69 The
  70 .Fn isatty
  71 function
  72 determines if the file descriptor
  73 .Fa fd
  74 refers to a valid
  75 terminal type device.
  76 .Pp
  77 The
  78 .Fn ttyname
  79 function
  80 gets the related device name of
  81 a file descriptor for which
  82 .Fn isatty
  83 is true.
  84 .Pp
  85 The
  86 .Fn ttyname
  87 function
  88 returns the name stored in a static buffer which will be overwritten
  89 on subsequent calls.
  90 The
  91 .Fn ttyname_r
  92 function
  93 takes a buffer and length as arguments to avoid this problem.
  94 .Pp
  95 The
  96 .Fn ttyslot
  97 function
  98 fetches the current process' control terminal number from the
  99 .Xr ttys 5
 100 file entry.
 101 .Sh RETURN VALUES
 102 The
 103 .Fn isatty
 104 function
 105 returns 1 if the file descriptor refers to a valid terminal
 106 device and 0 otherwise.
 107 .Pp
 108 The
 109 .Fn ttyname
 110 function
 111 returns the null terminated name if the device is found and
 112 .Fn isatty
 113 is true; otherwise
 114 a
 115 .Dv NULL
 116 pointer is returned.
 117 The
 118 .Fn ttyname_r
 119 function returns 0 if successful.
 120 Otherwise an error number is returned.
 121 .Pp
 122 The
 123 .Fn ttyslot
 124 function
 125 returns the unit number of the device file if found; otherwise
 126 the value zero is returned.
 127 .Sh FILES
 128 .Bl -tag -width ".Pa /etc/ttys" -compact
 129 .It Pa /dev/\(**
 130 .It Pa /etc/ttys
 131 .El
 132 .Sh ERRORS
 133 The
 134 .Fn ttyname ,
 135 .Fn ttyname_r ,
 136 and
 137 .Fn isatty
 138 functions
 139 may fail and return the following error codes:
 140 .Bl -tag -width Er
 141 .It Bq Er EBADF
 142 The
 143 .Fa fd
 144 is not a valid open file descriptor.
 145 .It Bq Er ENOTTY
 146 The
 147 .Fa fd
 148 is not associated with a terminal.
 149 .It Bq Er ERANGE
 150 The
 151 .Fa bufsize
 152 argument
 153 is smaller than the length of the string to be returned.
 154 .El
 155 .Sh SEE ALSO
 156 .Xr ioctl 2 ,
 157 .Xr ttys 5
 158 .Sh HISTORY
 159 The
 160 .Fn isatty ,
 161 .Fn ttyname ,
 162 and
 163 .Fn ttyslot
 164 functions
 165 appeared in
 166 .At v7 .
 167 The
 168 .Fn ttyname_r
 169 function
 170 appeared in
 171 .Fx 6.0 .