1.\" $NetBSD: cons.9,v 1.14 2003/05/01 08:42:08 uebayasi 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 April 1, 2003 35.Dt CONS 9 36.Os 37.Sh NAME 38.Nm cnbell , 39.Nm cnflush , 40.Nm cngetc , 41.Nm cngetsn , 42.Nm cnhalt , 43.Nm cnpollc , 44.Nm cnputc 45.Nd console access interface 46.Sh SYNOPSIS 47.In dev/cons.h 48.Ft void 49.Fn cnbell "u_int pitch" "u_int period" "u_int volume" 50.Ft void 51.Fn cnflush "void" 52.Ft int 53.Fn cngetc "void" 54.Ft int 55.Fn cngetsn "char *cp" "int size" 56.Ft void 57.Fn cnhalt "void" 58.Ft void 59.Fn cnpollc "int on" 60.Ft void 61.Fn cnputc "int c" 62.Sh DESCRIPTION 63These functions operate over current console device. 64The console must be initialized before these functions can be used. 65.Pp 66Console input polling functions 67.Fn cngetc , 68.Fn cngetsn 69and 70.Fn cnpollc 71are only to be used during initial system 72boot, e.g., when asking for root and dump device or to get 73necessary user input within mountroothooks. 74Once the system boots, user input is read via standard 75.Xr tty 4 76facilities. 77.Pp 78The following is a brief description of each function: 79.Bl -tag -width "cngetsn()" 80.It Fn cnbell 81Ring a bell at appropriate 82.Fa pitch , 83for duration of 84.Fa period 85milliseconds at given 86.Fa volume . 87Note that the 88.Fa volume 89value is ignored commonly. 90.It Fn cnflush 91Waits for all pending output to finish. 92.It Fn cngetc 93Poll (busy wait) for an input and return the input key. 94Returns 0 if there is no console input device. 95.Fn cnpollc 96.Em must 97be called before 98.Fn cngetc 99could be used. 100.Fn cngetc 101should be used during kernel startup only. 102.It Fn cngetsn 103Read one line of user input, stop reading once the newline 104key is input. 105Input is echoed back. 106This uses 107.Fn cnpollc 108and 109.Fn cngetc . 110Number of read characters is 111.Fa size 112at maximum, user is notified by console bell when the end 113of input buffer is reached. 114\*[Lt]Backspace\*[Gt] key works as expected. 115\*[Lt]@\*[Gt] or \*[Lt]CTRL\*[Gt]-u make 116.Fn cngetsn 117discard input read so far, print newline and 118wait for next input. 119.Fn cngetsn 120returns number of characters actually read, excluding 121the final newline. 122.Fa cp 123is 124.Em not 125zero-ended before return. 126.Fn cngetsn 127should be used during kernel startup only. 128.It Fn cnhalt 129Terminates the console device (i.e. cleanly shuts down the console hardware.) 130.It Fn cnpollc 131Switch the console driver to polling mode if 132.Fa on 133is nonzero, or back to interrupt driven mode if 134.Fa on 135is zero. 136.Fn cnpollc 137should be used during kernel startup only. 138.It Fn cnputc 139Console kernel output character routine. 140Commonly, kernel code uses 141.Xr printf 9 142rather than using this low-level interface. 143.El 144.Sh EXAMPLES 145This waits until a \*[Lt]Enter\*[Gt] key is pressed: 146.Pp 147.Bd -literal -compact 148int c; 149 150cnpollc(1); 151for(;;) { 152 c = cngetc(); 153 if ((c == '\\r' || (c == '\\n')) { 154 printf("\\n"); 155 break; 156 } 157} 158cnpollc(0); 159.Ed 160.Sh SEE ALSO 161.Xr pckbd 4 , 162.Xr pcppi 4 , 163.Xr tty 4 , 164.Xr wscons 4 , 165.Xr wskbd 4 , 166.Xr printf 9 , 167.Xr spl 9 , 168.Xr wscons 9 169