share/man/man9/cons.9

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