169 lines
4.6 KiB
Groff
169 lines
4.6 KiB
Groff
.\" $NetBSD: cons.9,v 1.15 2006/01/03 02:17:22 rumble Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
|
|
.\" 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 NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd April 1, 2003
|
|
.Dt CONS 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm cnbell ,
|
|
.Nm cnflush ,
|
|
.Nm cngetc ,
|
|
.Nm cngetsn ,
|
|
.Nm cnhalt ,
|
|
.Nm cnpollc ,
|
|
.Nm cnputc
|
|
.Nd console access interface
|
|
.Sh SYNOPSIS
|
|
.In dev/cons.h
|
|
.Ft void
|
|
.Fn cnbell "u_int pitch" "u_int period" "u_int volume"
|
|
.Ft void
|
|
.Fn cnflush "void"
|
|
.Ft int
|
|
.Fn cngetc "void"
|
|
.Ft int
|
|
.Fn cngetsn "char *cp" "int size"
|
|
.Ft void
|
|
.Fn cnhalt "void"
|
|
.Ft void
|
|
.Fn cnpollc "int on"
|
|
.Ft void
|
|
.Fn cnputc "int c"
|
|
.Sh DESCRIPTION
|
|
These functions operate over the current console device.
|
|
The console must be initialized before these functions can be used.
|
|
.Pp
|
|
Console input polling functions
|
|
.Fn cngetc ,
|
|
.Fn cngetsn
|
|
and
|
|
.Fn cnpollc
|
|
are only to be used during initial system
|
|
boot, e.g., when asking for root and dump device or to get
|
|
necessary user input within mountroothooks.
|
|
Once the system boots, user input is read via standard
|
|
.Xr tty 4
|
|
facilities.
|
|
.Pp
|
|
The following is a brief description of each function:
|
|
.Bl -tag -width "cngetsn()"
|
|
.It Fn cnbell
|
|
Ring a bell at appropriate
|
|
.Fa pitch ,
|
|
for duration of
|
|
.Fa period
|
|
milliseconds at given
|
|
.Fa volume .
|
|
Note that the
|
|
.Fa volume
|
|
value is ignored commonly.
|
|
.It Fn cnflush
|
|
Waits for all pending output to finish.
|
|
.It Fn cngetc
|
|
Poll (busy wait) for an input and return the input key.
|
|
Returns 0 if there is no console input device.
|
|
.Fn cnpollc
|
|
.Em must
|
|
be called before
|
|
.Fn cngetc
|
|
could be used.
|
|
.Fn cngetc
|
|
should be used during kernel startup only.
|
|
.It Fn cngetsn
|
|
Read one line of user input, stop reading once the newline
|
|
key is input.
|
|
Input is echoed back.
|
|
This uses
|
|
.Fn cnpollc
|
|
and
|
|
.Fn cngetc .
|
|
Number of read characters is
|
|
.Fa size
|
|
at maximum, user is notified by console bell when the end
|
|
of input buffer is reached.
|
|
\*[Lt]Backspace\*[Gt] key works as expected.
|
|
\*[Lt]@\*[Gt] or \*[Lt]CTRL\*[Gt]-u make
|
|
.Fn cngetsn
|
|
discard input read so far, print newline and
|
|
wait for next input.
|
|
.Fn cngetsn
|
|
returns number of characters actually read, excluding
|
|
the final newline.
|
|
.Fa cp
|
|
is
|
|
.Em not
|
|
zero-ended before return.
|
|
.Fn cngetsn
|
|
should be used during kernel startup only.
|
|
.It Fn cnhalt
|
|
Terminates the console device (i.e. cleanly shuts down the console hardware.)
|
|
.It Fn cnpollc
|
|
Switch the console driver to polling mode if
|
|
.Fa on
|
|
is nonzero, or back to interrupt driven mode if
|
|
.Fa on
|
|
is zero.
|
|
.Fn cnpollc
|
|
should be used during kernel startup only.
|
|
.It Fn cnputc
|
|
Console kernel output character routine.
|
|
Commonly, kernel code uses
|
|
.Xr printf 9
|
|
rather than using this low-level interface.
|
|
.El
|
|
.Sh EXAMPLES
|
|
This waits until a \*[Lt]Enter\*[Gt] key is pressed:
|
|
.Pp
|
|
.Bd -literal -compact
|
|
int c;
|
|
|
|
cnpollc(1);
|
|
for(;;) {
|
|
c = cngetc();
|
|
if ((c == '\\r' || (c == '\\n')) {
|
|
printf("\\n");
|
|
break;
|
|
}
|
|
}
|
|
cnpollc(0);
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr pckbd 4 ,
|
|
.Xr pcppi 4 ,
|
|
.Xr tty 4 ,
|
|
.Xr wscons 4 ,
|
|
.Xr wskbd 4 ,
|
|
.Xr printf 9 ,
|
|
.Xr spl 9 ,
|
|
.Xr wscons 9
|