original/man3/ttyslot.3

   1 .\" Copyright (C) 2002 Andries Brouwer <aeb@cwi.nl>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" This replaces an earlier man page written by Walter Harms
  26 .\" <walter.harms@informatik.uni-oldenburg.de>.
  27 .\"
  28 .TH TTYSLOT 3 2013-07-22 "GNU" "Linux Programmer's Manual"
  29 .SH NAME
  30 ttyslot \- find the slot of the current user's terminal in some file
  31 .SH SYNOPSIS
  32 .BR "#include <unistd.h>"       "    /* on BSD-like systems, and Linux */"
  33 .br
  34 .BR "#include <stdlib.h>"       "    /* on System V-like systems */"
  35 .sp
  36 .B "int ttyslot(void);"
  37 .sp
  38 .in -4n
  39 Feature Test Macro Requirements for glibc (see
  40 .BR feature_test_macros (7)):
  41 .in
  42 .sp
  43 .ad l
  44 .BR ttyslot ():
  45 .RS 4
  46 _BSD_SOURCE ||
  47 .br
  48 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_\ <\ 500\ &&\ _XOPEN_SOURCE_EXTENDED
  49 .RE
  50 .ad b
  51 .SH DESCRIPTION
  52 The legacy function
  53 .BR ttyslot ()
  54 returns the index of the current user's entry in some file.
  55 .LP
  56 Now "What file?" you ask.
  57 Well, let's first look at some history.
  58 .SS Ancient history
  59 There used to be a file
  60 .I /etc/ttys
  61 in UNIX V6, that was read by the
  62 .BR init (8)
  63 program to find out what to do with each terminal line.
  64 Each line consisted of three characters.
  65 The first character was either \(aq0\(aq or \(aq1\(aq,
  66 where \(aq0\(aq meant "ignore".
  67 The second character denoted the terminal: \(aq8\(aq stood for "/dev/tty8".
  68 The third character was an argument to
  69 .BR getty (8)
  70 indicating the sequence of line speeds to try (\(aq\-\(aq was: start trying
  71 110 baud).
  72 Thus a typical line was "18\-".
  73 A hang on some line was solved by changing the \(aq1\(aq to a \(aq0\(aq,
  74 signaling init, changing back again, and signaling init again.
  75 .LP
  76 In UNIX V7 the format was changed: here the second character
  77 was the argument to
  78 .BR getty (8)
  79 indicating the sequence of line speeds to try (\(aq0\(aq was: cycle through
  80 300-1200-150-110 baud; \(aq4\(aq was for the on-line console DECwriter)
  81 while the rest of the line contained the name of the tty.
  82 Thus a typical line was "14console".
  83 .LP
  84 Later systems have more elaborate syntax.
  85 System V-like systems have
  86 .I /etc/inittab
  87 instead.
  88 .SS Ancient history (2)
  89 On the other hand, there is the file
  90 .I /etc/utmp
  91 listing the people currently logged in.
  92 It is maintained by
  93 .BR login (1).
  94 It has a fixed size, and the appropriate index in the file was
  95 determined by
  96 .BR login (1)
  97 using the
  98 .BR ttyslot ()
  99 call to find the number of the line in
 100 .I /etc/ttys
 101 (counting from 1).
 102 .SS The semantics of ttyslot
 103 Thus, the function
 104 .BR ttyslot ()
 105 returns the index of the controlling terminal of the calling process
 106 in the file
 107 .IR /etc/ttys ,
 108 and that is (usually) the same as the index of the entry for the
 109 current user in the file
 110 .IR /etc/utmp .
 111 BSD still has the
 112 .I /etc/ttys
 113 file, but System V-like systems do not, and hence cannot refer to it.
 114 Thus, on such systems the documentation says that
 115 .BR ttyslot ()
 116 returns the current user's index in the user accounting data base.
 117 .SH RETURN VALUE
 118 If successful, this function returns the slot number.
 119 On error (e.g., if none of the file descriptors 0, 1 or 2 is
 120 associated with a terminal that occurs in this data base)
 121 it returns 0 on UNIX V6 and V7 and BSD-like systems,
 122 but \-1 on System V-like systems.
 123 .SH ATTRIBUTES
 124 .SS Multithreading (see pthreads(7))
 125 The
 126 .BR ttyslot ()
 127 function calls thread-unsafe function
 128 .BR getttyent (),
 129 so it is not thread-safe.
 130 .SH CONFORMING TO
 131 SUSv1; marked as LEGACY in SUSv2; removed in POSIX.1-2001.
 132 SUSv2 requires \-1 on error.
 133 .SH NOTES
 134 The utmp file is found various places on various systems, such as
 135 .IR /etc/utmp ,
 136 .IR /var/adm/utmp ,
 137 .IR /var/run/utmp .
 138 .LP
 139 The glibc2 implementation of this function reads the file
 140 .BR _PATH_TTYS ,
 141 defined in
 142 .I <ttyent.h>
 143 as "/etc/ttys".
 144 It returns 0 on error.
 145 Since Linux systems do not usually have "/etc/ttys", it will
 146 always return 0.
 147 .LP
 148 Minix also has
 149 .IR fttyslot ( fd ).
 150 .\" .SH HISTORY
 151 .\" .BR ttyslot ()
 152 .\" appeared in UNIX V7.
 153 .SH SEE ALSO
 154 .BR getttyent (3),
 155 .BR ttyname (3),
 156 .BR utmp (5)
 157 .SH COLOPHON
 158 This page is part of release 3.65 of the Linux
 159 .I man-pages
 160 project.
 161 A description of the project,
 162 and information about reporting bugs,
 163 can be found at
 164 \%http://www.kernel.org/doc/man\-pages/.