diff options
Diffstat (limited to 'share/examples/mdoc')
| -rw-r--r-- | share/examples/mdoc/POSIX-copyright | 36 | ||||
| -rw-r--r-- | share/examples/mdoc/deshallify.sh | 75 | ||||
| -rw-r--r-- | share/examples/mdoc/example.1 | 155 | ||||
| -rw-r--r-- | share/examples/mdoc/example.3 | 335 | ||||
| -rw-r--r-- | share/examples/mdoc/example.4 | 123 | ||||
| -rw-r--r-- | share/examples/mdoc/example.9 | 343 |
6 files changed, 1067 insertions, 0 deletions
diff --git a/share/examples/mdoc/POSIX-copyright b/share/examples/mdoc/POSIX-copyright new file mode 100644 index 000000000000..144b15559307 --- /dev/null +++ b/share/examples/mdoc/POSIX-copyright @@ -0,0 +1,36 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) [year] [your name] +.\" +.\" 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 AUTHOR 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 AUTHOR 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. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" diff --git a/share/examples/mdoc/deshallify.sh b/share/examples/mdoc/deshallify.sh new file mode 100644 index 000000000000..b0493f5033d0 --- /dev/null +++ b/share/examples/mdoc/deshallify.sh @@ -0,0 +1,75 @@ +#!/bin/sh +# Script to remove shall clauses. +# +# +sed -e 's/s shall define/s define/g' \ + -e 's/shall define/defines/g' \ + -e 's/shall attempt/attempts/g' \ + -e 's/shall include/includes/g' \ + -e 's/shall return zero and have/returns zero and has/g' \ + -e 's/shall return/returns/g' \ + -e 's/shall also include/also includes/g' \ + -e 's/pipe or FIFO shall be /pipe of FIFO are /g' \ + -e 's/s shall be /s are /g' \ + -e 's/shall be /is /g' \ + -e 's/s shall create/s create/g' \ + -e 's/shall create /creates /g' \ + -e 's/shall perform/performs/g' \ + -e 's/shall affect the/affect the/g' \ + -e 's/s shall have/s have/g' \ + -e 's/shall have/has/g' \ + -e 's/shall transfer/transfers/g' \ + -e 's/shall block/blocks/g' \ + -e 's/shall not block/does not block/g' \ + -e 's/shall occur/occurs/g' \ + -e 's/shall complete/complete/g' \ + -e 's/shall mark for update/marks for update/g' \ + -e 's/s shall fail/s fail/g' \ + -e 's/shall fail/fails/g' \ + -e 's/s shall generate/s generate/g' \ + -e 's/shall generate/generates/g' \ + -e 's/shall place/places/g' \ + -e 's/s shall default/s default/g' \ + -e 's/shall default/defaults/g' \ + -e 's/pplications shall ensure/pplications must ensure/g' \ + -e 's/pplication shall ensure/pplication must ensure/g' \ + -e 's/shall always begin/always begins/g' \ + -e 's/s shall begin /s begin /g' \ + -e 's/shall begin /begins /g' \ + -e 's/shall always contain /always contains /g' \ + -e 's/shall produce/produces/g' \ + -e 's/shall appear/appears/g' \ + -e 's/s shall be$/s are/g' \ + -e 's/shall be$/is/g' \ + -e 's/which shall result /which results /g' \ + -e 's/s shall not/s are not/g' \ + -e 's/shall not be/is not/g' \ + -e 's/shall not/is not/g' \ + -e 's/s shall behave/s behave/g' \ + -e 's/shall behave/behaves/g' \ + -e 's/shall specify/specifies/g' \ + -e 's/s shall override/s override/g' \ + -e 's/shall override/overrides/g' \ + -e 's/shall apply /applies /g' \ + -e 's/s shall start/s start/g' \ + -e 's/shall start /starts /g' \ + -e 's/s shall affect/s affect/g' \ + -e 's/shall affect/affects/g' \ + -e 's/s shall indicate/s indicate/g' \ + -e 's/shall indicate/indicates/g' \ + -e 's/shall set /set /g' \ + -e 's/s shall recognize/s recognize/g' \ + -e 's/shall recognize /recognizes /g' \ + -e 's/shall also be /is also /g' \ + -e 's/s shall enter/s enter/g' \ + -e 's/shall enter /enters /g' \ + -e 's/shall take /take /g' \ + -e 's/they shall only take /they only take /g' \ + -e 's/shall consist /consist /g' \ + -e 's/s shall cause/s cause/g' \ + -e 's/shall cause/causes/g' \ + -e 's/s shall replace/s replace/g' \ + -e 's/shall replace/replaces/g' \ + -e 's/shall become/becomes/g' \ + -e 's/shall each consist/each consist/g' \ + $1 > $1.x diff --git a/share/examples/mdoc/example.1 b/share/examples/mdoc/example.1 new file mode 100644 index 000000000000..0bdabe95aa95 --- /dev/null +++ b/share/examples/mdoc/example.1 @@ -0,0 +1,155 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) [year] [your name] +.\" +.\" 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 AUTHOR 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 AUTHOR 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. +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd December 8, 1999 +.Dt EXAMPLE 1 +.Os +.Sh NAME +.Nm example +.Nd "example command manual page" +.Sh SYNOPSIS +.Nm +.Op Fl abc +.Op Fl d Ar argument +.Ar file +.Sh DESCRIPTION +This is an example manual page for the +.Nm +command. +It is intended that this example can be used as a template +when writing a new manual page. +.Pp +The options are as follows: +.Bl -tag -width "-d argument" +.It Fl a +Example optional +.Fl a +option. +.It Fl b +Example optional +.Fl b +option. +.It Fl c +Example optional +.Fl c +option. +.It Fl d Ar argument +Example optional +.Fl d +option with required argument +.Ar argument . +.It Ar file +Required argument +.Ar file . +.El +.Sh ENVIRONMENT +The +.Nm +command ignores the +.Ev EXAMPLE +environment variable. +.Sh FILES +.Bl -tag -width "/dev/null" -compact +.It Pa /dev/null +Example of a file in the +.Sx FILES +section. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +The following is an example of a typical usage +of the +.Nm +command: +.Pp +.Dl "example -abc -d xyzzy /dev/null" +.Sh DIAGNOSTICS +The command may fail for one of the following reasons: +.Bl -diag +.It "example error message" +An example of an error message. +.It "another example error message." +Self explanatory. +.El +.Sh COMPATIBILITY +The +.Nm +command has no known compatibility issues. +.Sh SEE ALSO +.Xr example 3 , +.Xr example 4 , +.Xr mdoc 7 , +.Xr example 9 +.Rs +.%A "A. B. Author" +.%T "Example RFC Title" +.%O RFC0000 +.Re +.Rs +.%A "A. B. Author" +.%B "Example Book Title" +.%O ISBN-0-000-00000-0 +.Re +.Rs +.%A "A. B. Author" +.%D "January 1997" +.%J "Example Journal Name" +.%T "Example Article Title" +.Re +.Sh STANDARDS +If the command conforms to some standard, such as +.St -p1003.2 +or +.St -isoC , +it should be noted here. +.Sh HISTORY +The +.Nm +manual page example first appeared in +.Fx 2.2 . +.Pp +Some other common +.Sx HISTORY +section examples are: +.Pp +The +.Nm +manual page example first appeared in +.Bx 4.4 . +.Pp +The +.Nm +manual page example first appeared in +.At v6 . +.Sh AUTHORS +This +manual page was written by +.An Mike Pritchard Aq Mt mpp@FreeBSD.org . +.Sh BUGS +The actual code for this command is vaporware. diff --git a/share/examples/mdoc/example.3 b/share/examples/mdoc/example.3 new file mode 100644 index 000000000000..c4e85062cad1 --- /dev/null +++ b/share/examples/mdoc/example.3 @@ -0,0 +1,335 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) [year] [your name] +.\" +.\" 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 AUTHOR 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 AUTHOR 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. +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd July 30, 2004 +.Dt EXAMPLE 3 +.Os +.Sh NAME +.Nm example +.Nd "example library function manual page" +.Sh LIBRARY +.\" Note: list of available libraries is available in mdoc(7) +.Lb libc +.Sh SYNOPSIS +.In example.h +.Ft int +.Fn example "char *ptr" "int mode" +.Sh DESCRIPTION +This is an example library function manual page for the +.Fn example +function. +It is intended that this example can be used as a template +when writing a new manual page. +.Pp +The +.Fn example +function takes two arguments: +.Fa ptr +and +.Fa mode . +The argument +.Fa mode +may have one of the following values: +.Bl -tag -width "EXAMPLE_ONE" +.It Dv EXAMPLE_ONE +First example of a defined variable. +.Dv EXAMPLE_ONE +is described below. +.It Dv EXAMPLE_TWO +Second example. +.El +.Pp +The above values are defined in +.In example.h +as follows: +.Bd -literal +#define EXAMPLE_ONE 1 +#define EXAMPLE_TWO 2 +.Ed +.Sh IMPLEMENTATION NOTES +The +.Fn example +function is not actually implemented. +.Sh RETURN VALUES +.Rv -std example +.Sh ENVIRONMENT +The +.Fn example +library function ignores the +.Ev EXAMPLE +environment variable. +.Sh FILES +.Bl -tag -width "/dev/null" -compact +.It Pa /dev/null +Example of a file in the +.Sx FILES +section. +.El +.Sh DIAGNOSTICS +None. +.Sh COMPATIBILITY +The +.Fn example +function has no known compatibility issues. +.Sh ERRORS +.\" Delete any errno's that are not returned by your +.\" function or system call and then tailor the +.\" remaining text as needed. +The +.Fn example +function will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +Operation not permitted. +.It Bq Er ENOENT +No such file or directory. +.It Bq Er ESRCH +No such process. +.It Bq Er EINTR +Interrupted system call. +.It Bq Er EIO +Input/output error. +.It Bq Er ENXIO +Device not configured. +.It Bq Er E2BIG +Argument list too long. +.It Bq Er ENOEXEC +Exec format error. +.It Bq Er EBADF +Bad file descriptor. +.It Bq Er ECHILD +No child processes. +.It Bq Er EDEADLK +Resource deadlock avoided. +.It Bq Er ENOMEM +Cannot allocate memory. +.It Bq Er EACCES +Permission denied. +.It Bq Er EFAULT +Bad address. +.It Bq Er ENOTBLK +Block device required. +.It Bq Er EBUSY +Device busy. +.It Bq Er EEXIST +File exists. +.It Bq Er EXDEV +Cross-device link. +.It Bq Er ENODEV +Operation not supported by device. +.It Bq Er ENOTDIR +Not a directory. +.It Bq Er EISDIR +Is a directory. +.It Bq Er EINVAL +Invalid argument. +.It Bq Er ENFILE +Too many open files in system. +.It Bq Er EMFILE +Too many open files. +.It Bq Er ENOTTY +Inappropriate ioctl for device. +.It Bq Er ETXTBSY +Text file busy. +.It Bq Er EFBIG +File too large. +.It Bq Er ENOSPC +No space left on device. +.It Bq Er ESPIPE +Illegal seek. +.It Bq Er EROFS +Read-only file system. +.It Bq Er EMLINK +Too many links. +.It Bq Er EPIPE +Broken pipe. +.It Bq Er EDOM +Numerical argument out of domain. +.It Bq Er ERANGE +Result too large. +.It Bq Er EAGAIN +Resource temporarily unavailable. +.It Bq Er EWOULDBLOCK +Operation would block. +.It Bq Er EINPROGRESS +Operation now in progress. +.It Bq Er EALREADY +Operation already in progress. +.It Bq Er ENOTSOCK +Socket operation on non-socket. +.It Bq Er EDESTADDRREQ +Destination address required. +.It Bq Er EMSGSIZE +Message too long. +.It Bq Er EPROTOTYPE +Protocol wrong type for socket. +.It Bq Er ENOPROTOOPT +Protocol not available. +.It Bq Er EPROTONOSUPPORT +Protocol not supported. +.It Bq Er ESOCKTNOSUPPORT +Socket type not supported. +.It Bq Er EOPNOTSUPP +Operation not supported. +.It Bq Er EPFNOSUPPORT +Protocol family not supported. +.It Bq Er EAFNOSUPPORT +Address family not supported by protocol family. +.It Bq Er EADDRINUSE +Address already in use. +.It Bq Er EADDRNOTAVAIL +Cannot assign requested address. +.It Bq Er ENETDOWN +Network is down. +.It Bq Er ENETUNREACH +Network is unreachable. +.It Bq Er ENETRESET +Network dropped connection on reset. +.It Bq Er ECONNABORTED +Software causes connection abort. +.It Bq Er ENOBUFS +No buffer space available. +.It Bq Er EISCONN +Socket is already connected. +.It Bq Er ENOTCONN +Socket is not connected. +.It Bq Er ESHUTDOWN +Cannot send after socket shutdown. +.It Bq Er ETOOMANYREFS +Too many references: cannot splice. +.It Bq Er ETIMEDOUT +Operation timed out. +.It Bq Er ECONNREFUSED +Connection refused. +.It Bq Er ELOOP +Too many levels of symbolic links. +.It Bq Er ENAMETOOLONG +File name too long. +.It Bq Er EHOSTDOWN +Host is down. +.It Bq Er EHOSTUNREACH +No route to host. +.It Bq Er ENOTEMPTY +Directory not empty. +.It Bq Er EPROCLIM +Too many processes. +.It Bq Er EUSERS +Too many users. +.It Bq Er EDQUOT +Disc quota exceeded. +.It Bq Er ESTALE +Stale NFS file handle. +.It Bq Er EREMOTE +Too many levels of remote in path. +.It Bq Er EBADRPC +RPC struct is bad. +.It Bq Er ERPCMISMATCH +RPC version wrong. +.It Bq Er EPROGUNAVAIL +RPC program not available. +.It Bq Er EPROGMISMATCH +Program version wrong. +.It Bq Er EPROCUNAVAIL +Bad procedure for program. +.It Bq Er ENOLCK +No locks available. +.It Bq Er ENOSYS +Function not implemented. +.It Bq Er EFTYPE +Inappropriate file type or format. +.It Bq Er EAUTH +Authentication error. +.It Bq Er ENEEDAUTH +Need authenticator. +.It Bq Er EIDRM +Identifier removed. +.It Bq Er ENOMSG +No message of desired type. +.It Bq Er EOVERFLOW +Value too large to be stored in data type. +.It Bq Er ECANCELED +Operation canceled. +.It Bq Er EILSEQ +Illegal byte sequence. +.It Bq Er ENOATTR +Attribute not found. +.It Bq Er EDOOFUS +Programming error. +.El +.Sh SEE ALSO +.Xr example 1 , +.Xr example 4 , +.Xr mdoc 7 , +.Xr example 9 +.Rs +.%A "A. B. Author" +.%T "Example RFC Title" +.%O RFC0000 +.Re +.Rs +.%A "A. B. Author" +.%B "Example Book Title" +.%O ISBN-0-000-00000-0 +.Re +.Rs +.%A "A. B. Author" +.%D "January 1997" +.%J "Example Journal Name" +.%T "Example Article Title" +.Re +.Sh STANDARDS +If the function conforms to some standard, such as +.St -p1003.1-2004 +or +.St -isoC-99 , +it should be noted here. +.Sh HISTORY +The +.Nm +manual page example first appeared in +.Fx 2.2 . +.Pp +Some other common +.Sx HISTORY +section examples are: +.Pp +The +.Nm +manual page example first appeared in +.Bx 4.4 . +.Pp +The +.Nm +manual page example first appeared in +.At v6 . +.Sh AUTHORS +This +manual page was written by +.An Mike Pritchard Aq Mt mpp@FreeBSD.org . +.Sh BUGS +The actual code for this function is vaporware. diff --git a/share/examples/mdoc/example.4 b/share/examples/mdoc/example.4 new file mode 100644 index 000000000000..47ae5456b79a --- /dev/null +++ b/share/examples/mdoc/example.4 @@ -0,0 +1,123 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) [year] [your name] +.\" +.\" 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 AUTHOR 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 AUTHOR 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. +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd July 31, 2015 +.Dt EXAMPLE 4 i386 +.Os +.Sh NAME +.Nm example +.Nd "example device driver manual page" +.Sh SYNOPSIS +To compile the driver into the kernel, +place the following lines in the +kernel configuration file: +.Bd -ragged -offset indent +.Cd "device example" +.Cd "options EXAMPLE_DEBUG" +.Ed +.Pp +Alternatively, to load the driver as a +module at boot time, place the following line in +.Xr loader.conf 5 : +.Bd -literal -offset indent +example_load="YES" +.Ed +.Sh DESCRIPTION +This is an example device driver manual page for the +.Nm +driver. +It is intended that this example can be used as a template +when writing a new manual page. +.Pp +The +.Nm +driver supports the following ioctls: +.Bl -tag -width "EIOCNULL" +.It Dv EIOCEX +Example ioctl. +.It Dv EIOCNULL +Example ioctl. +.El +.Pp +If the kernel is compiled with the +.Dv EXAMPLE_DEBUG +option, then additional debugging messages will be displayed. +.Sh HARDWARE +The +.Nm +driver supports the following example hardware: +.Pp +.Bl -bullet -compact +.It +Example device 4201 +.It +Example device 4202 +.El +.Sh FILES +.Bl -tag -width "/dev/null" -compact +.It Pa /dev/null +Example of a file in the +.Sx FILES +section. +.El +.Sh DIAGNOSTICS +.Bl -diag +.It "example%d: example diagnostic message." +An example of a diagnostic message. +.It "example%d: another example diagnostic message." +Self explanatory. +.El +.Sh SEE ALSO +.Xr example 1 , +.Xr example 3 , +.Xr mdoc 7 , +.Xr example 9 +.Sh HISTORY +The +.Nm +device driver first appeared in +.Fx 2.2 . +.Pp +Some other common +.Sx HISTORY +section examples are: +.Pp +The +.Nm +manual page example first appeared in +.Bx 4.4 . +.Pp +The +.Nm +manual page example first appeared in +.At v6 . +.Sh AUTHORS +This manual page was written by +.An Mike Pritchard Aq Mt mpp@FreeBSD.org . +.Sh BUGS +The actual code for this device driver is vaporware. diff --git a/share/examples/mdoc/example.9 b/share/examples/mdoc/example.9 new file mode 100644 index 000000000000..1dd24a99fd42 --- /dev/null +++ b/share/examples/mdoc/example.9 @@ -0,0 +1,343 @@ +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) [year] [your name] +.\" +.\" 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 AUTHOR 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 AUTHOR 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. +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd September 27, 2006 +.Dt EXAMPLE 9 +.Os +.Sh NAME +.Nm example +.Nd "example kernel interface manual page" +.Sh SYNOPSIS +.In sys/example.h +.Ft int +.Fn example "char *ptr" "int mode" +.Sh DESCRIPTION +This is an example manual page for the +.Fn example +kernel function. +It is intended that this example can be used as a template +when writing a new manual page. +.Pp +The +.Fn example +function takes two arguments: +.Fa ptr +and +.Fa mode . +The argument +.Fa mode +may have one of the following values: +.Bl -tag -width "EXAMPLE_ONE" +.It Dv EXAMPLE_ONE +First example of a defined variable. +.Dv EXAMPLE_ONE +is described below. +.It Dv EXAMPLE_TWO +Second example. +.El +.Pp +The above values are defined in +.In example.h +as follows: +.Bd -literal +#define EXAMPLE_ONE 1 +#define EXAMPLE_TWO 2 +.Ed +.Sh IMPLEMENTATION NOTES +The +.Fn example +function is not actually implemented. +.Sh LOCKING +The +.Va example_lock +lock must be held before +.Fn example +is called. +.Pp +Since +.Va example_lock +is a +.Xr mutex 9 , +no sleepable locks (i.e., +.Xr sx 9 +locks) can be acquired in +.Fn example . +.Sh RETURN VALUES +The +.Fn example +function returns the value 0 if successful; +otherwise one of the values listed in the +.Sx ERRORS +section is returned, to indicate the error. +.Sh EXAMPLES +.Bd -literal + int error; + + mtx_lock(&example_lock); + if ((error = example(NULL, EXAMPLE_ONE)) != 0) { + mtx_unlock(&example_lock); + return (error); + } + mtx_unlock(&example_lock); +.Ed +.Sh COMPATIBILITY +The +.Fn example +function has no known compatibility issues. +.Sh ERRORS +.\" Delete any errno's that are not returned by your +.\" function or system call and then tailor the +.\" remaining text as needed. +The +.Fn example +function will fail if: +.Bl -tag -width Er +.It Bq Er EPERM +Operation not permitted. +.It Bq Er ENOENT +No such file or directory. +.It Bq Er ESRCH +No such process. +.It Bq Er EINTR +Interrupted system call. +.It Bq Er EIO +Input/output error. +.It Bq Er ENXIO +Device not configured. +.It Bq Er E2BIG +Argument list too long. +.It Bq Er ENOEXEC +Exec format error. +.It Bq Er EBADF +Bad file descriptor. +.It Bq Er ECHILD +No child processes. +.It Bq Er EDEADLK +Resource deadlock avoided. +.It Bq Er ENOMEM +Cannot allocate memory. +.It Bq Er EACCES +Permission denied. +.It Bq Er EFAULT +Bad address. +.It Bq Er ENOTBLK +Block device required. +.It Bq Er EBUSY +Device busy. +.It Bq Er EEXIST +File exists. +.It Bq Er EXDEV +Cross-device link. +.It Bq Er ENODEV +Operation not supported by device. +.It Bq Er ENOTDIR +Not a directory. +.It Bq Er EISDIR +Is a directory. +.It Bq Er EINVAL +Invalid argument. +.It Bq Er ENFILE +Too many open files in system. +.It Bq Er EMFILE +Too many open files. +.It Bq Er ENOTTY +Inappropriate ioctl for device. +.It Bq Er ETXTBSY +Text file busy. +.It Bq Er EFBIG +File too large. +.It Bq Er ENOSPC +No space left on device. +.It Bq Er ESPIPE +Illegal seek. +.It Bq Er EROFS +Read-only file system. +.It Bq Er EMLINK +Too many links. +.It Bq Er EPIPE +Broken pipe. +.It Bq Er EDOM +Numerical argument out of domain. +.It Bq Er ERANGE +Result too large. +.It Bq Er EAGAIN +Resource temporarily unavailable. +.It Bq Er EWOULDBLOCK +Operation would block. +.It Bq Er EINPROGRESS +Operation now in progress. +.It Bq Er EALREADY +Operation already in progress. +.It Bq Er ENOTSOCK +Socket operation on non-socket. +.It Bq Er EDESTADDRREQ +Destination address required. +.It Bq Er EMSGSIZE +Message too long. +.It Bq Er EPROTOTYPE +Protocol wrong type for socket. +.It Bq Er ENOPROTOOPT +Protocol not available. +.It Bq Er EPROTONOSUPPORT +Protocol not supported. +.It Bq Er ESOCKTNOSUPPORT +Socket type not supported. +.It Bq Er EOPNOTSUPP +Operation not supported. +.It Bq Er EPFNOSUPPORT +Protocol family not supported. +.It Bq Er EAFNOSUPPORT +Address family not supported by protocol family. +.It Bq Er EADDRINUSE +Address already in use. +.It Bq Er EADDRNOTAVAIL +Cannot assign requested address. +.It Bq Er ENETDOWN +Network is down. +.It Bq Er ENETUNREACH +Network is unreachable. +.It Bq Er ENETRESET +Network dropped connection on reset. +.It Bq Er ECONNABORTED +Software causes connection abort. +.It Bq Er ENOBUFS +No buffer space available. +.It Bq Er EISCONN +Socket is already connected. +.It Bq Er ENOTCONN +Socket is not connected. +.It Bq Er ESHUTDOWN +Cannot send after socket shutdown. +.It Bq Er ETOOMANYREFS +Too many references: cannot splice. +.It Bq Er ETIMEDOUT +Operation timed out. +.It Bq Er ECONNREFUSED +Connection refused. +.It Bq Er ELOOP +Too many levels of symbolic links. +.It Bq Er ENAMETOOLONG +File name too long. +.It Bq Er EHOSTDOWN +Host is down. +.It Bq Er EHOSTUNREACH +No route to host. +.It Bq Er ENOTEMPTY +Directory not empty. +.It Bq Er EPROCLIM +Too many processes. +.It Bq Er EUSERS +Too many users. +.It Bq Er EDQUOT +Disc quota exceeded. +.It Bq Er ESTALE +Stale NFS file handle. +.It Bq Er EREMOTE +Too many levels of remote in path. +.It Bq Er EBADRPC +RPC struct is bad. +.It Bq Er ERPCMISMATCH +RPC version wrong. +.It Bq Er EPROGUNAVAIL +RPC program not available. +.It Bq Er EPROGMISMATCH +Program version wrong. +.It Bq Er EPROCUNAVAIL +Bad procedure for program. +.It Bq Er ENOLCK +No locks available. +.It Bq Er ENOSYS +Function not implemented. +.It Bq Er EFTYPE +Inappropriate file type or format. +.It Bq Er EAUTH +Authentication error. +.It Bq Er ENEEDAUTH +Need authenticator. +.It Bq Er EIDRM +Identifier removed. +.It Bq Er ENOMSG +No message of desired type. +.It Bq Er EOVERFLOW +Value too large to be stored in data type. +.It Bq Er ECANCELED +Operation canceled. +.It Bq Er EILSEQ +Illegal byte sequence. +.It Bq Er ENOATTR +Attribute not found. +.It Bq Er EDOOFUS +Programming error. +.El +.Sh SEE ALSO +.Xr example 1 , +.Xr example 3 , +.Xr example 4 , +.Xr mdoc 7 , +.Xr mutex 9 +.Rs +.%A "A. B. Author" +.%T "Example RFC Title" +.%O RFC0000 +.Re +.Rs +.%A "A. B. Author" +.%B "Example Book Title" +.%O ISBN-0-000-00000-0 +.Re +.Rs +.%A "A. B. Author" +.%D "January 1997" +.%J "Example Journal Name" +.%T "Example Article Title" +.Re +.Sh HISTORY +The +.Nm +manual page example first appeared in +.Fx 6.0 . +.Pp +Some other common +.Sx HISTORY +section examples are: +.Pp +The +.Nm +manual page example first appeared in +.Bx 4.4 . +.Pp +The +.Nm +manual page example first appeared in +.At v6 . +.Sh AUTHORS +This +manual page was written by +.An Giorgos Keramidas Aq Mt keramida@FreeBSD.org . +.Sh BUGS +The actual code for this function is vaporware. |