lib/libc/gen/getttyent.3

   1 .\" Copyright (c) 1989, 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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)getttyent.3 8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/gen/getttyent.3,v 1.9.2.4 2003/03/13 18:05:37 trhodes Exp $
  34 .\"
  35 .Dd November 17, 1996
  36 .Dt GETTTYENT 3
  37 .Os
  38 .Sh NAME
  39 .Nm getttyent ,
  40 .Nm getttynam ,
  41 .Nm setttyent ,
  42 .Nm endttyent
  43 .Nd get ttys file entry
  44 .Nm isdialuptty ,
  45 .Nm isnettty
  46 .Nd determine tty type from ttys file entry
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In ttyent.h
  51 .Ft struct ttyent *
  52 .Fn getttyent void
  53 .Ft struct ttyent *
  54 .Fn getttynam "const char *name"
  55 .Ft int
  56 .Fn setttyent void
  57 .Ft int
  58 .Fn endttyent void
  59 .Ft int
  60 .Fn isdialuptty "const char *name"
  61 .Ft int
  62 .Fn isnettty "const char *name"
  63 .Sh DESCRIPTION
  64 The
  65 .Fn getttyent ,
  66 and
  67 .Fn getttynam
  68 functions
  69 each return a pointer to an object, with the following structure,
  70 containing the broken-out fields of a line from the tty description
  71 file.
  72 .Bd -literal
  73 struct ttyent {
  74         char    *ty_name;       /* terminal device name */
  75         char    *ty_getty;      /* command to execute, usually getty */
  76         char    *ty_type;       /* terminal type for termcap */
  77 #define TTY_ON          0x01    /* enable logins (start ty_getty program) */
  78 #define TTY_SECURE      0x02    /* allow uid of 0 to login */
  79 #define TTY_DIALUP      0x04    /* is a dialup tty */
  80 #define TTY_NETWORK     0x08    /* is a network tty */
  81         int     ty_status;      /* status flags */
  82         char    *ty_window;     /* command to start up window manager */
  83         char    *ty_comment;    /* comment field */
  84         char    *ty_group;      /* tty group name */
  85 };
  86 .Ed
  87 .Pp
  88 The fields are as follows:
  89 .Bl -tag -width ty_comment
  90 .It Fa ty_name
  91 The name of the character-special file.
  92 .It Fa ty_getty
  93 The name of the command invoked by
  94 .Xr init 8
  95 to initialize tty line characteristics.
  96 .It Fa ty_type
  97 The name of the default terminal type connected to this tty line.
  98 .It Fa ty_status
  99 A mask of bit fields which indicate various actions allowed on this
 100 tty line.
 101 The possible flags are as follows:
 102 .Bl -tag -width TTY_NETWORK
 103 .It Dv TTY_ON
 104 Enables logins (i.e.,
 105 .Xr init 8
 106 will start the command referenced by
 107 .Fa ty_getty
 108 on this entry).
 109 .It Dv TTY_SECURE
 110 Allow users with a uid of 0 to login on this terminal.
 111 .It Dv TTY_DIALUP
 112 Identifies a tty as a dialin line.
 113 If this flag is set, then
 114 .Fn isdialuptty
 115 will return a non-zero value.
 116 .It Dv TTY_NETWORK
 117 Identifies a tty used for network connections.
 118 If this flag is set, then
 119 .Fn isnettty
 120 will return a non-zero value.
 121 .El
 122 .It Fa ty_window
 123 The command to execute for a window system associated with the line.
 124 .It Fa ty_group
 125 A group name to which the tty belongs.
 126 If no group is specified in the ttys description file,
 127 then the tty is placed in an anonymous group called "none".
 128 .It Fa ty_comment
 129 Any trailing comment field, with any leading hash marks (``#'') or
 130 whitespace removed.
 131 .El
 132 .Pp
 133 If any of the fields pointing to character strings are unspecified,
 134 they are returned as null pointers.
 135 The field
 136 .Fa ty_status
 137 will be zero if no flag values are specified.
 138 .Pp
 139 See
 140 .Xr ttys 5
 141 for a more complete discussion of the meaning and usage of the
 142 fields.
 143 .Pp
 144 The
 145 .Fn getttyent
 146 function
 147 reads the next line from the ttys file, opening the file if necessary.
 148 The
 149 .Fn setttyent
 150 function
 151 rewinds the file if open, or opens the file if it is unopened.
 152 The
 153 .Fn endttyent
 154 function
 155 closes any open files.
 156 .Pp
 157 The
 158 .Fn getttynam
 159 function
 160 searches from the beginning of the file until a matching
 161 .Fa name
 162 is found
 163 (or until
 164 .Dv EOF
 165 is encountered).
 166 .Sh RETURN VALUES
 167 The routines
 168 .Fn getttyent
 169 and
 170 .Fn getttynam
 171 return a null pointer on
 172 .Dv EOF
 173 or error.
 174 The
 175 .Fn setttyent
 176 function
 177 and
 178 .Fn endttyent
 179 return 0 on failure and 1 on success.
 180 .Pp
 181 The routines
 182 .Fn isdialuptty
 183 and
 184 .Fn isnettty
 185 return non-zero if the dialup or network flag is set for the
 186 tty entry relating to the tty named by the argument, and
 187 zero otherwise.
 188 .Sh FILES
 189 .Bl -tag -width /etc/ttys -compact
 190 .It Pa /etc/ttys
 191 .El
 192 .Sh SEE ALSO
 193 .Xr login 1 ,
 194 .Xr ttyslot 3 ,
 195 .Xr gettytab 5 ,
 196 .Xr termcap 5 ,
 197 .Xr ttys 5 ,
 198 .Xr getty 8 ,
 199 .Xr init 8
 200 .Sh HISTORY
 201 The
 202 .Fn getttyent ,
 203 .Fn getttynam ,
 204 .Fn setttyent ,
 205 and
 206 .Fn endttyent
 207 functions appeared in
 208 .Bx 4.3 .
 209 .Sh BUGS
 210 These functions use static data storage;
 211 if the data is needed for future use, it should be
 212 copied before any subsequent calls overwrite it.