xref: /freebsd/lib/libc/gen/getttyent.3 (revision c98323078dede7579020518ec84cdcb478e5c142)
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$
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.Nm isdialuptty ,
44.Nm isnettty
45.Nd
46.Xr ttys 5
47file routines
48.Sh LIBRARY
49.Lb libc
50.Sh SYNOPSIS
51.In ttyent.h
52.Ft struct ttyent *
53.Fn getttyent void
54.Ft struct ttyent *
55.Fn getttynam "const char *name"
56.Ft int
57.Fn setttyent void
58.Ft int
59.Fn endttyent void
60.Ft int
61.Fn isdialuptty "const char *name"
62.Ft int
63.Fn isnettty "const char *name"
64.Sh DESCRIPTION
65The
66.Fn getttyent ,
67and
68.Fn getttynam
69functions
70each return a pointer to an object, with the following structure,
71containing the broken-out fields of a line from the tty description
72file.
73.Bd -literal
74struct ttyent {
75	char	*ty_name;	/* terminal device name */
76	char	*ty_getty;	/* command to execute, usually getty */
77	char	*ty_type;	/* terminal type for termcap */
78#define	TTY_ON		0x01	/* enable logins (start ty_getty program) */
79#define	TTY_SECURE	0x02	/* allow uid of 0 to login */
80#define	TTY_DIALUP	0x04	/* is a dialup tty */
81#define	TTY_NETWORK	0x08	/* is a network tty */
82	int	ty_status;	/* status flags */
83	char	*ty_window;	/* command to start up window manager */
84	char	*ty_comment;	/* comment field */
85	char	*ty_group;	/* tty group name */
86};
87.Ed
88.Pp
89The fields are as follows:
90.Bl -tag -width ty_comment
91.It Fa ty_name
92The name of the character-special file.
93.It Fa ty_getty
94The name of the command invoked by
95.Xr init 8
96to initialize tty line characteristics.
97.It Fa ty_type
98The name of the default terminal type connected to this tty line.
99.It Fa ty_status
100A mask of bit fields which indicate various actions allowed on this
101tty line.
102The possible flags are as follows:
103.Bl -tag -width TTY_NETWORK
104.It Dv TTY_ON
105Enables logins (i.e.,
106.Xr init 8
107will start the command referenced by
108.Fa ty_getty
109on this entry).
110.It Dv TTY_SECURE
111Allow users with a uid of 0 to login on this terminal.
112.It Dv TTY_DIALUP
113Identifies a tty as a dialin line.
114If this flag is set, then
115.Fn isdialuptty
116will return a non-zero value.
117.It Dv TTY_NETWORK
118Identifies a tty used for network connections.
119If this flag is set, then
120.Fn isnettty
121will return a non-zero value.
122.El
123.It Fa ty_window
124The command to execute for a window system associated with the line.
125.It Fa ty_group
126A group name to which the tty belongs.
127If no group is specified in the ttys description file,
128then the tty is placed in an anonymous group called "none".
129.It Fa ty_comment
130Any trailing comment field, with any leading hash marks (``#'') or
131whitespace removed.
132.El
133.Pp
134If any of the fields pointing to character strings are unspecified,
135they are returned as null pointers.
136The field
137.Fa ty_status
138will be zero if no flag values are specified.
139.Pp
140See
141.Xr ttys 5
142for a more complete discussion of the meaning and usage of the
143fields.
144.Pp
145The
146.Fn getttyent
147function
148reads the next line from the ttys file, opening the file if necessary.
149The
150.Fn setttyent
151function
152rewinds the file if open, or opens the file if it is unopened.
153The
154.Fn endttyent
155function
156closes any open files.
157.Pp
158The
159.Fn getttynam
160function
161searches from the beginning of the file until a matching
162.Fa name
163is found
164(or until
165.Dv EOF
166is encountered).
167.Sh RETURN VALUES
168The routines
169.Fn getttyent
170and
171.Fn getttynam
172return a null pointer on
173.Dv EOF
174or error.
175The
176.Fn setttyent
177function
178and
179.Fn endttyent
180return 0 on failure and 1 on success.
181.Pp
182The routines
183.Fn isdialuptty
184and
185.Fn isnettty
186return non-zero if the dialup or network flag is set for the
187tty entry relating to the tty named by the argument, and
188zero otherwise.
189.Sh FILES
190.Bl -tag -width /etc/ttys -compact
191.It Pa /etc/ttys
192.El
193.Sh SEE ALSO
194.Xr login 1 ,
195.Xr ttyslot 3 ,
196.Xr gettytab 5 ,
197.Xr termcap 5 ,
198.Xr ttys 5 ,
199.Xr getty 8 ,
200.Xr init 8
201.Sh HISTORY
202The
203.Fn getttyent ,
204.Fn getttynam ,
205.Fn setttyent ,
206and
207.Fn endttyent
208functions appeared in
209.Bx 4.3 .
210.Sh BUGS
211These functions use static data storage;
212if the data is needed for future use, it should be
213copied before any subsequent calls overwrite it.
214