1.\" $NetBSD: cons.9,v 1.8 2002/10/14 13:43:18 wiz 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. 58The console has to 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. 68Once the system boots, 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. 96Input is echoed back. 97This uses 98.Fn cnpollc 99and 100.Fn cngetc . 101Number of read characters is 102.Fa size 103at maximum, user is notified by console bell when the end 104of input buffer is reached. 105\*[Lt]Backspace\*[Gt] key works as expected. 106\*[Lt]@\*[Gt] or \*[Lt]CTRL\*[Gt]-u make 107.Fn cngetsn 108discard input read so far, print newline and 109wait for next input. 110.Fn cngetsn 111returns number of characters actually read, excluding 112the final newline. 113.Fa cp 114is 115.Em not 116zero-ended before return. 117.Fn cngetsn 118should be used during kernel startup only. 119.It Fn cnpollc 120Switch the console driver to polling mode if 121.Fa on 122is nonzero, or back to interrupt driven mode if 123.Fa on 124is zero. 125.Fn cnpollc 126should be used during kernel startup only. 127.It Fn cnputc 128Console kernel output character routine. 129Commonly, kernel code uses 130.Xr printf 9 131rather than using this low-level interface. 132.El 133.Sh EXAMPLES 134This waits until a \*[Lt]Enter\*[Gt] key is pressed: 135.Pp 136.Bd -literal -compact 137int c; 138 139cnpollc(1); 140for(;;) { 141 c = cngetc(); 142 if ((c == '\\r' || (c == '\\n')) { 143 printf("\\n"); 144 break; 145 } 146} 147cnpollc(0); 148.Ed 149.Sh SEE ALSO 150.Xr pckbd 4 , 151.Xr pcppi 4 , 152.Xr tty 4 , 153.Xr wscons 4 , 154.Xr wskbd 4 , 155.Xr printf 9 , 156.Xr spl 9 , 157.Xr wscons 9 158