[unix-history] / lib / libc / gen / getttyent.3

.\" Copyright (c) 1989, 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)getttyent.3	6.7 (Berkeley) 4/19/91
.\"
.Dd April 19, 1991
.Dt GETTTYENT 3
.Os BSD 4.3
.Sh NAME
.Nm getttyent ,
.Nm getttynam ,
.Nm setttyent ,
.Nm endttyent
.Nd get ttys file entry
.Sh SYNOPSIS
.Fd #include <ttyent.h>
.Ft struct ttyent *
.Fn getttyent
.Ft struct ttyent *
.Fn getttynam "char *name"
.Ft int
.Fn setttyent void
.Ft int
.Fn endttyent void
.Sh DESCRIPTION
The
.Fn getttyent ,
and
.Fn getttynam
functions
each return a pointer to an object, with the following structure,
containing the broken-out fields of a line from the tty description
file.
.Bd -literal
struct ttyent {
	char	*ty_name;	/* terminal device name */
	char	*ty_getty;	/* command to execute */
	char	*ty_type;	/* terminal type */
#define	TTY_ON		0x01	/* enable logins */
#define	TTY_SECURE	0x02	/* allow uid of 0 to login */
	int	ty_status;	/* flag values */
	char	*ty_window;	/* command for window manager */
	char	*ty_comment;	/* comment field */
};
.Ed
.Pp
The fields are as follows:
.Bl -tag -width ty_comment
.It Fa ty_name
The name of the character-special file.
.It Fa ty_getty
The name of the command invoked by
.Xr init 8
to initialize tty line characteristics.
.It Fa ty_type
The name of the default terminal type connected to this tty line.
.It Fa ty_status
A mask of bit fields which indicate various actions allowed on this
tty line.
The possible flags are as follows:
.Bl -tag -width TTY_SECURE
.It Dv TTY_ON
Enables logins (i.e.,
.Xr init 8
will start the command referenced by
.Fa ty_getty
on this entry).
.It Dv TTY_SECURE
Allow users with a uid of 0 to login on this terminal.
.El
.It Fa ty_window
The command to execute for a window system associated with the line.
.It Fa ty_comment
Any trailing comment field, with any leading hash marks (``#'') or
whitespace removed.
.El
.Pp
If any of the fields pointing to character strings are unspecified,
they are returned as null pointers.
The field
.Fa ty_status
will be zero if no flag values are specified.
.Pp
See
.Xr ttys 5
for a more complete discussion of the meaning and usage of the
fields.
.Pp
The
.Fn getttyent
function
reads the next line from the ttys file, opening the file if necessary.
The
.Fn setttyent
function
rewinds the file if open, or opens the file if it is unopened.
The
.Fn endttyent
function
closes any open files.
.Pp
The
.Fn getttynam
function
searches from the beginning of the file until a matching
.Fa name
is found
(or until
.Dv EOF
is encountered).
.Sh RETURN VALUES
The routines
.Fn getttyent
and
.Fn getttynam
return a null pointer on
.Dv EOF
or error.
The
.Fn setttyent
function
and
.Fn endttyent
return 0 on failure and 1 on success.
.Sh FILES
.Bl -tag -width /etc/ttys -compact
.It Pa /etc/ttys
.El
.Sh SEE ALSO
.Xr login 1 ,
.Xr ttyslot 3 ,
.Xr gettytab 5 ,
.Xr termcap 5 ,
.Xr ttys 5 ,
.Xr getty 8 ,
.Xr init 8
.Sh HISTORY
The
.Fn getttyent ,
.Fn getttynam ,
.Fn setttyent ,
and
.Fn endttyent
functions appeared in
.Bx 4.3 .
.Sh BUGS
These functions use static data storage;
if the data is needed for future use, it should be
copied before any subsequent calls overwrite it.
Commit	Line	Data
15637ed4 RG	1	.\" Copyright (c) 1989, 1991 The Regents of the University of California.
	2	.\" 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 6.7 (Berkeley) 4/19/91
	33	.\"
	34	.Dd April 19, 1991
	35	.Dt GETTTYENT 3
	36	.Os BSD 4.3
	37	.Sh NAME
	38	.Nm getttyent ,
	39	.Nm getttynam ,
	40	.Nm setttyent ,
	41	.Nm endttyent
	42	.Nd get ttys file entry
	43	.Sh SYNOPSIS
	44	.Fd #include <ttyent.h>
	45	.Ft struct ttyent *
	46	.Fn getttyent
	47	.Ft struct ttyent *
	48	.Fn getttynam "char *name"
	49	.Ft int
	50	.Fn setttyent void
	51	.Ft int
	52	.Fn endttyent void
	53	.Sh DESCRIPTION
	54	The
	55	.Fn getttyent ,
	56	and
	57	.Fn getttynam
	58	functions
	59	each return a pointer to an object, with the following structure,
	60	containing the broken-out fields of a line from the tty description
	61	file.
	62	.Bd -literal
	63	struct ttyent {
	64	char ty_name; / terminal device name */
65	char ty_getty; / command to execute */
66	char ty_type; / terminal type */
67	#define TTY_ON 0x01 /* enable logins */
68	#define TTY_SECURE 0x02 /* allow uid of 0 to login */
69	int ty_status; /* flag values */
70	char ty_window; / command for window manager */
71	char ty_comment; / comment field */
72	};
73	.Ed
74	.Pp
75	The fields are as follows:
76	.Bl -tag -width ty_comment
77	.It Fa ty_name
78	The name of the character-special file.
79	.It Fa ty_getty
80	The name of the command invoked by
81	.Xr init 8
82	to initialize tty line characteristics.
83	.It Fa ty_type
84	The name of the default terminal type connected to this tty line.
85	.It Fa ty_status
86	A mask of bit fields which indicate various actions allowed on this
87	tty line.
88	The possible flags are as follows:
89	.Bl -tag -width TTY_SECURE
90	.It Dv TTY_ON
91	Enables logins (i.e.,
92	.Xr init 8
93	will start the command referenced by
94	.Fa ty_getty
95	on this entry).
96	.It Dv TTY_SECURE
97	Allow users with a uid of 0 to login on this terminal.
98	.El
99	.It Fa ty_window
100	The command to execute for a window system associated with the line.
101	.It Fa ty_comment
102	Any trailing comment field, with any leading hash marks (``#'') or
103	whitespace removed.
104	.El
105	.Pp
106	If any of the fields pointing to character strings are unspecified,
107	they are returned as null pointers.
108	The field
109	.Fa ty_status
110	will be zero if no flag values are specified.
111	.Pp
112	See
113	.Xr ttys 5
114	for a more complete discussion of the meaning and usage of the
115	fields.
116	.Pp
117	The
118	.Fn getttyent
119	function
120	reads the next line from the ttys file, opening the file if necessary.
121	The
122	.Fn setttyent
123	function
124	rewinds the file if open, or opens the file if it is unopened.
125	The
126	.Fn endttyent
127	function
128	closes any open files.
129	.Pp
130	The
131	.Fn getttynam
132	function
133	searches from the beginning of the file until a matching
134	.Fa name
135	is found
136	(or until
137	.Dv EOF
138	is encountered).
139	.Sh RETURN VALUES
140	The routines
141	.Fn getttyent
142	and
143	.Fn getttynam
144	return a null pointer on
145	.Dv EOF
146	or error.
147	The
148	.Fn setttyent
149	function
150	and
151	.Fn endttyent
152	return 0 on failure and 1 on success.
153	.Sh FILES
154	.Bl -tag -width /etc/ttys -compact
155	.It Pa /etc/ttys
156	.El
157	.Sh SEE ALSO
158	.Xr login 1 ,
159	.Xr ttyslot 3 ,
160	.Xr gettytab 5 ,
161	.Xr termcap 5 ,
162	.Xr ttys 5 ,
163	.Xr getty 8 ,
164	.Xr init 8
165	.Sh HISTORY
166	The
167	.Fn getttyent ,
168	.Fn getttynam ,
169	.Fn setttyent ,
170	and
171	.Fn endttyent
172	functions appeared in
173	.Bx 4.3 .
174	.Sh BUGS
175	These functions use static data storage;
176	if the data is needed for future use, it should be
177	copied before any subsequent calls overwrite it.