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