xref: /minix/lib/libc/gen/getttyent.3 (revision 0a6a1f1d) 
1.\"	$NetBSD: getttyent.3,v 1.21 2014/02/07 20:20:56 christos Exp $
2.\"
3.\" Copyright (c) 1989, 1991, 1993
4.\"	The Regents of the University of California.  All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\"    notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\"    notice, this list of conditions and the following disclaimer in the
13.\"    documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\"    may be used to endorse or promote products derived from this software
16.\"    without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\"     @(#)getttyent.3	8.1 (Berkeley) 6/4/93
31.\"
32.Dd February 7, 2014
33.Dt GETTTYENT 3
34.Os
35.Sh NAME
36.Nm getttyent ,
37.Nm getttynam ,
38.Nm setttyent ,
39.Nm setttyentpath ,
40.Nm endttyent
41.Nd get ttys file entry
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In ttyent.h
46.Ft struct ttyent *
47.Fn getttyent void
48.Ft struct ttyent *
49.Fn getttynam "const char *name"
50.Ft int
51.Fn setttyent void
52.Ft int
53.Fn setttyentpath "const char *path"
54.Ft int
55.Fn endttyent void
56.Sh DESCRIPTION
57The
58.Fn getttyent ,
59and
60.Fn getttynam
61functions
62each return a pointer to an object, with the following structure,
63containing the broken-out fields of a line from the tty description
64file.
65.Bd -literal
66struct ttyent {
67	char	*ty_name;	/* terminal device name */
68	char	*ty_getty;	/* command to execute */
69	char	*ty_type;	/* terminal type */
70#define	TTY_ON		0x01	/* enable logins */
71#define	TTY_SECURE	0x02	/* allow uid of 0 to login */
72#define	TTY_LOCAL	0x04	/* set 'CLOCAL' on open (dev. specific) */
73#define	TTY_RTSCTS	0x08	/* set 'CRTSCTS' on open (dev. specific) */
74#define	TTY_SOFTCAR	0x10	/* ignore hardware carrier (dev. spec.) */
75#define	TTY_MDMBUF	0x20	/* set 'MDMBUF' on open (dev. specific) */
76#define	TTY_DTRCTS	0x40	/* set 'CDTRCTS' on open (dev. specific) */
77	int	ty_status;	/* flag values */
78	char	*ty_window;	/* command for window manager */
79	char	*ty_comment;	/* comment field */
80	char	*ty_class;	/* category of tty usage */
81};
82.Ed
83.Pp
84The fields are as follows:
85.Bl -tag -width ty_comment
86.It Fa ty_name
87The name of the character-special file.
88.It Fa ty_getty
89The name of the command invoked by
90.Xr init 8
91to initialize tty line characteristics.
92.It Fa ty_type
93The name of the default terminal type connected to this tty line.
94.It Fa ty_status
95A mask of bit fields which indicate various actions allowed on this
96tty line.
97The possible flags are as follows:
98.Bl -tag -width TTY_SOFTCAR
99.It Dv TTY_ON
100Enables logins (i.e.,
101.Xr init 8
102will start the command referenced by
103.Fa ty_getty
104on this entry).
105.It Dv TTY_SECURE
106Allow users with a uid of 0 to login on this terminal.
107.It Dv TTY_LOCAL
108If the terminal port's driver supports it, cause the line
109to be treated as ``local.''
110.It Dv TTY_MDMBUF
111If the terminal port's driver supports it, use
112DTR/DCD hardware flow control on the line by default.
113.It Dv TTY_RTSCTS
114If the terminal port's driver supports it, use
115full-duplex RTS/CTS hardware flow control on the line
116by default.
117.It Dv TTY_SOFTCAR
118If the terminal port's driver supports it, ignore hardware
119carrier on the line.
120.El
121.It Fa ty_window
122The command to execute for a window system associated with the line.
123.It Fa ty_comment
124Any trailing comment field, with any leading hash marks (``#'') or
125whitespace removed.
126.It Fa ty_class
127A key indexing into a capfile style database (/etc/ttyclasses)
128of attributes for this class of tty.
129No attributes are currently defined or used,
130so there are currently no functions to retrieve them.
131.El
132.Pp
133If any of the fields pointing to character strings are unspecified,
134they are returned as null pointers.
135The field
136.Fa ty_status
137will be zero if no flag values are specified.
138.Pp
139See
140.Xr ttys 5
141for a more complete discussion of the meaning and usage of the
142fields.
143.Pp
144The
145.Fn getttyent
146function
147reads the next line from the ttys file, opening the file if necessary.
148The
149.Fn setttyent
150function
151rewinds the file if open, or opens the file if it is unopened.
152The
153.Fn setttyentpath
154function
155is equivalent to
156.Fn setttyent
157but accepts an additional argument to read the ttys information from
158an alternate file instead of the default location
159.Pq defined in Dv _PATH_TTYS .
160The
161.Fn endttyent
162function
163closes any open files.
164.Pp
165The
166.Fn getttynam
167function
168searches from the beginning of the file until a matching
169.Fa name
170is found
171(or until
172.Dv EOF
173is encountered).
174.Sh RETURN VALUES
175The routines
176.Fn getttyent
177and
178.Fn getttynam
179return a null pointer on
180.Dv EOF
181or error.
182The
183.Fn setttyent
184and
185.Fn setttyentpath
186functions
187and
188.Fn endttyent
189return 0 on failure and 1 on success.
190.Sh FILES
191.Bl -tag -width /etc/ttys -compact
192.It Pa /etc/ttys
193.El
194.Sh SEE ALSO
195.Xr login 1 ,
196.Xr ttyslot 3 ,
197.Xr capfile 5 ,
198.Xr gettytab 5 ,
199.Xr ttys 5 ,
200.Xr getty 8 ,
201.Xr init 8 ,
202.Xr ttyflags 8
203.Sh HISTORY
204The
205.Fn getttyent ,
206.Fn getttynam ,
207.Fn setttyent ,
208and
209.Fn endttyent
210functions appeared in
211.Bx 4.3 .
212The
213.Fn setttyentpath
214function appeared in
215.Nx 4.0 .
216.Sh BUGS
217These functions use static data storage;
218if the data is needed for future use, it should be
219copied before any subsequent calls overwrite it.
220