1.\" $NetBSD: cons.9,v 1.6 2002/02/13 08:18:39 ross Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" 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. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the NetBSD 17.\" Foundation, Inc. and its contributors. 18.\" 4. Neither the name of The NetBSD Foundation nor the names of its 19.\" contributors may be used to endorse or promote products derived 20.\" from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 23.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 24.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 25.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 26.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 27.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 30.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32.\" POSSIBILITY OF SUCH DAMAGE. 33.\" 34.Dd June 2, 2001 35.Dt CONS 9 36.Os 37.Sh NAME 38.Nm cnbell , 39.Nm cngetc , 40.Nm cngetsn , 41.Nm cnpollc , 42.Nm cnputc 43.Nd console access interface 44.Sh SYNOPSIS 45.Fd #include \*[Lt]dev/cons.h\*[Gt] 46.Ft void 47.Fn cnbell "u_int pitch" "u_int period" "u_int volume" 48.Ft int 49.Fn cngetc "void" 50.Ft int 51.Fn cngetsn "char *cp" "int size" 52.Ft void 53.Fn cnpollc "int on" 54.Ft void 55.Fn cnputc "int c" 56.Sh DESCRIPTION 57These functions operate over current console device. The console has 58to be initialized first, before these functions could be used. 59.Pp 60Console input polling functions 61.Fn cngetc , 62.Fn cngetsn 63and 64.Fn cnpollc 65are only to be used during initial system 66boot, e.g. when asking for root and dump device or to get 67necessary user input within mountroothooks. Once the system 68boots, user input is read via standard 69.Xr tty 4 70facilities. 71.Pp 72The following is a brief description of each function: 73.Bl -tag -width "cngetsn()" 74.It Fn cnbell 75Ring a bell at appropriate 76.Fa pitch , 77for duration of 78.Fa period 79milliseconds at given 80.Fa volume . 81Note that the 82.Fa volume 83value is ignored commonly. 84.It Fn cngetc 85Poll (busy wait) for a input and return the input key. 86.Fn cnpollc 87.Em must 88be called before 89.Fn cngetc 90could be used. 91.Fn cngetc 92should be used during kernel startup only. 93.It Fn cngetsn 94Read one line of user input, stop reading once the newline 95key is input. Input is echoed back. This 96uses 97.Fn cnpollc 98and 99.Fn cngetc . 100Number of read characters is 101.Fa size 102at maximum, user is notified by console bell when the end 103of input buffer is reached. \*[Lt]Backspace\*[Gt] key 104works as expected. \*[Lt]@\*[Gt] or \*[Lt]CTRL\*[Gt]-u make 105.Fn cngetsn 106discard input read so far, print newline and 107wait for next input. 108.Fn cngetsn 109returns number of characters actually read, excluding 110the final newline. 111.Fa cp 112is 113.Em not 114zero-ended before return. 115.Fn cngetsn 116should be used during kernel startup only. 117.It Fn cnpollc 118Switch the console driver to polling mode if 119.Fa on 120is nonzero, or back to interrupt driven mode if 121.Fa on 122is zero. 123.Fn cnpollc 124should be used during kernel startup only. 125.It Fn cnputc 126Console kernel output character routine. Commonly, kernel code uses 127.Xr printf 9 128rather than using this low-level interface. 129.El 130.Sh EXAMPLES 131This waits until a \*[Lt]Enter\*[Gt] key is pressed: 132.Pp 133.Bd -literal -compact 134int c; 135 136cnpollc(1); 137for(;;) { 138 c = cngetc(); 139 if ((c == '\\r' || (c == '\\n')) { 140 printf("\\n"); 141 break; 142 } 143} 144cnpollc(0); 145.Ed 146.Sh SEE ALSO 147.Xr pckbd 4 , 148.Xr pcppi 4 , 149.Xr tty 4 , 150.Xr wscons 4 , 151.Xr wskbd 4 , 152.Xr printf 9 , 153.Xr spl 9 154