[src/uebayasi-xip]: src/share/man/man9 grammar in kprintf.9 (s/or/and/ and ad...

[cnst <cnst%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3deea1e76a4d
branches:  uebayasi-xip
changeset: 751580:3deea1e76a4d
user:      cnst <cnst%NetBSD.org@localhost>
date:      Wed Feb 17 22:04:15 2010 +0000

description:
grammar in kprintf.9 (s/or/and/ and add some commas);   ok wiz, pgoyette

diffstat:

 share/man/man9/kprintf.9 |  305 +++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 305 insertions(+), 0 deletions(-)

diffs (truncated from 309 to 300 lines):

diff -r 048ee4e8d7eb -r 3deea1e76a4d share/man/man9/kprintf.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/kprintf.9  Wed Feb 17 22:04:15 2010 +0000
@@ -0,0 +1,305 @@
+.\"     $NetBSD: kprintf.9,v 1.29.2.2 2010/02/17 22:04:15 cnst Exp $
+.\"
+.\" Copyright (c) 1998, 2002, 2007 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Jeremy Cooper and by Jason R. Thorpe.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd September 4, 2009
+.Dt KPRINTF 9
+.Os
+.Sh NAME
+.Nm printf ,
+.Nm snprintf ,
+.Nm vprintf ,
+.Nm vsnprintf ,
+.Nm uprintf ,
+.Nm ttyprintf ,
+.Nm tprintf ,
+.Nm aprint
+.Nd kernel formatted output conversion
+.Sh SYNOPSIS
+.In sys/systm.h
+.Ft void
+.Fn "printf" "const char *format" "..."
+.Ft void
+.Fn "printf_nolog" "const char *format" "..."
+.Ft int
+.Fn "snprintf" "char *buf" "size_t size" "const char *format" "..."
+.In machine/stdarg.h
+.Ft void
+.Fn "vprintf" "const char *format" "va_list ap"
+.Ft int
+.Fn "vsnprintf" "char *buf" "size_t size" "const char *format" "va_list ap"
+.Ft void
+.Fn "uprintf" "const char *format" "..."
+.Ft void
+.Fn "ttyprintf" "struct tty *tty" "const char *format" "..."
+.In sys/tprintf.h
+.Ft tpr_t
+.Fn "tprintf_open" "struct proc *p"
+.Ft void
+.Fn "tprintf" "tpr_t tpr" "const char *format" "..."
+.Ft void
+.Fn "tprintf_close" "tpr_t tpr"
+.Ft void
+.Fn "aprint_normal" "const char *format" "..."
+.Ft void
+.Fn "aprint_naive" "const char *format" "..."
+.Ft void
+.Fn "aprint_verbose" "const char *format" "..."
+.Ft void
+.Fn "aprint_debug" "const char *format" "..."
+.Ft void
+.Fn "aprint_error" "const char *format" "..."
+.Ft void
+.Fn "aprint_normal_dev" "device_t" "const char *format" "..."
+.Ft void
+.Fn "aprint_naive_dev" "device_t" "const char *format" "..."
+.Ft void
+.Fn "aprint_verbose_dev" "device_t" "const char *format" "..."
+.Ft void
+.Fn "aprint_debug_dev" "device_t" "const char *format" "..."
+.Ft void
+.Fn "aprint_error_dev" "device_t" "const char *format" "..."
+.Ft void
+.Fn "aprint_normal_ifnet" "struct ifnet *" "const char *format" "..."
+.Ft void
+.Fn "aprint_naive_ifnet" "struct ifnet *" "const char *format" "..."
+.Ft void
+.Fn "aprint_verbose_ifnet" "struct ifnet *" "const char *format" "..."
+.Ft void
+.Fn "aprint_debug_ifnet" "struct ifnet *" "const char *format" "..."
+.Ft void
+.Fn "aprint_error_ifnet" "struct ifnet *" "const char *format" "..."
+.Ft int
+.Fn "aprint_get_error_count" "void"
+.Sh DESCRIPTION
+The
+.Fn printf
+family of functions allows the kernel to send formatted messages to various
+output devices.
+The functions
+.Fn printf
+and
+.Fn vprintf
+send formatted strings to the system console.
+The
+.Fn printf_nolog
+function is identical to
+.Fn printf ,
+except it does not send the data to the system log.
+The functions
+.Fn snprintf
+and
+.Fn vsnprintf
+write output to a string buffer.
+These four functions work similarly to their user space counterparts,
+and are not described in detail here.
+.Pp
+The functions
+.Fn uprintf
+and
+.Fn ttyprintf
+send formatted strings to the current process's controlling tty and a specific
+tty, respectively.
+.Pp
+The
+.Fn tprintf
+function sends formatted strings to a process's controlling tty,
+via a handle of type tpr_t.
+This allows multiple write operations to the tty with a guarantee that the
+tty will be valid across calls.
+A handle is acquired by calling
+.Fn tprintf_open
+with the target process as an argument.
+This handle must be closed with a matching call to
+.Fn tprintf_close .
+.Pp
+The functions
+.Fn aprint_normal ,
+.Fn aprint_naive ,
+.Fn aprint_verbose ,
+.Fn aprint_debug ,
+and
+.Fn aprint_error
+are intended to be used to print
+.Xr autoconf 9
+messages.
+Their verbosity depends on flags set in the
+.Va boothowto
+variable, through options passed during bootstrap; see
+.Xr boothowto 9
+and
+.Sx Interactive mode
+in
+.Xr boot 8 :
+.Bl -tag -width AB_VERBOSE
+.It Dv AB_SILENT
+silent mode, enabled by
+.Ic boot
+.Fl z .
+.It Dv AB_QUIET
+quiet mode, enabled by
+.Ic boot
+.Fl q .
+.It Dv AB_VERBOSE
+verbose mode, enabled by
+.Ic boot
+.Fl v .
+.It Dv AB_DEBUG
+debug mode, enabled by
+.Ic boot
+.Fl x .
+.El
+.Pp
+The
+.Fn aprint_*
+functions have the following behaviour, based on the above
+mentioned flags:
+.Bl -tag -width Xaprint_verboseXXX
+.It Fn aprint_normal
+Sends to the console unless
+.Dv AB_QUIET
+is set.
+Always sends to the log.
+.It Fn aprint_naive
+Sends to the console only if
+.Dv AB_QUIET
+is set.
+Never sends to the log.
+.It Fn aprint_verbose
+Sends to the console only if
+.Dv AB_VERBOSE
+is set.
+Always sends to the log.
+.It Fn aprint_debug
+Sends to the console and the log only if
+.Dv AB_DEBUG
+is set.
+.It Fn aprint_error
+Like
+.Fn aprint_normal ,
+but also keeps track of the number of times called.
+This allows a subsystem to report the number of errors that occurred
+during a quiet or silent initialization phase.
+.El
+.Pp
+For the
+.Fn aprint_*
+functions there are two additional families of functions with the
+suffixes
+.Dv _dev
+and
+.Dv _ifnet
+which work like their counterparts without the suffixes, except that
+they take a
+.Ft device_t
+and
+.Ft struct ifnet * ,
+respectively, as first argument,
+and prefix the log message with the
+corresponding device or interface name.
+.Pp
+The
+.Fn aprint_get_error_count
+function reports the number of errors and resets the counter to 0.
+.Pp
+If
+.Dv AB_SILENT
+is set, none of the autoconfiguration message printing routines send output
+to the console.
+The
+.Dv AB_VERBOSE
+and
+.Dv AB_DEBUG
+flags override
+.Dv AB_SILENT .
+.Sh RETURN VALUES
+The
+.Fn snprintf
+and
+.Fn vsnprintf
+functions return the number of characters placed in the buffer
+.Fa buf .
+This is different to the user-space functions of the same name.
+.Pp
+The
+.Fn tprintf_open
+function returns
+.Dv NULL
+if no terminal handle could be acquired.
+.Sh SEE ALSO
+.Xr printf 1 ,
+.Xr printf 3 ,
+.Xr snprintb 3 ,
+.Xr boot 8 ,
+.Xr autoconf 9 ,
+.Xr boothowto 9
+.Sh CODE REFERENCES
+.Pa sys/kern/subr_prf.c
+.Sh HISTORY
+The
+.Fn sprintf
+and
+.Fn vsprintf
+unsized string formatting functions are supported for compatibility only,
+and are not documented here.
+New code should use the size-limited
+.Fn snprintf
+and
+.Fn vsnprintf
+functions instead.
+.Pp
+In
+.Nx 1.5
+and earlier,
+.Fn printf
+supported more format strings than the user space
+.Fn printf .
+These nonstandard format strings are no longer supported.
+For the functionality provided by the former
+.Li %b
+format string, see
+.Xr snprintb 3 .
+.Pp
+The
+.Fn aprint_normal ,
+.Fn aprint_naive ,
+.Fn aprint_verbose ,
+and
+.Fn aprint_debug
+functions first appeared in
+.Bsx .
+.Sh BUGS