SPDX-License-Identifier: BSD-2-Clause-FreeBSD
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 n 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.
p The .Fn example function takes two arguments: .Fa ptr and .Fa mode . The argument .Fa mode may have one of the following values: l -tag -width "EXAMPLE_ONE" t Dv EXAMPLE_ONE First example of a defined variable. .Dv EXAMPLE_ONE is described below. t Dv EXAMPLE_TWO Second example. .El
p The above values are defined in n example.h as follows: d -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.
p
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
d -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:
l -tag -width Er t Bq Er EPERM Operation not permitted.
t Bq Er ENOENT No such file or directory.
t Bq Er ESRCH No such process.
t Bq Er EINTR Interrupted system call.
t Bq Er EIO Input/output error.
t Bq Er ENXIO Device not configured.
t Bq Er E2BIG Argument list too long.
t Bq Er ENOEXEC Exec format error.
t Bq Er EBADF Bad file descriptor.
t Bq Er ECHILD No child processes.
t Bq Er EDEADLK Resource deadlock avoided.
t Bq Er ENOMEM Cannot allocate memory.
t Bq Er EACCES Permission denied.
t Bq Er EFAULT Bad address.
t Bq Er ENOTBLK Block device required.
t Bq Er EBUSY Device busy.
t Bq Er EEXIST File exists.
t Bq Er EXDEV Cross-device link.
t Bq Er ENODEV Operation not supported by device.
t Bq Er ENOTDIR Not a directory.
t Bq Er EISDIR Is a directory.
t Bq Er EINVAL Invalid argument.
t Bq Er ENFILE Too many open files in system.
t Bq Er EMFILE Too many open files.
t Bq Er ENOTTY Inappropriate ioctl for device.
t Bq Er ETXTBSY Text file busy.
t Bq Er EFBIG File too large.
t Bq Er ENOSPC No space left on device.
t Bq Er ESPIPE Illegal seek.
t Bq Er EROFS Read-only file system.
t Bq Er EMLINK Too many links.
t Bq Er EPIPE Broken pipe.
t Bq Er EDOM Numerical argument out of domain.
t Bq Er ERANGE Result too large.
t Bq Er EAGAIN Resource temporarily unavailable.
t Bq Er EWOULDBLOCK Operation would block.
t Bq Er EINPROGRESS Operation now in progress.
t Bq Er EALREADY Operation already in progress.
t Bq Er ENOTSOCK Socket operation on non-socket.
t Bq Er EDESTADDRREQ Destination address required.
t Bq Er EMSGSIZE Message too long.
t Bq Er EPROTOTYPE Protocol wrong type for socket.
t Bq Er ENOPROTOOPT Protocol not available.
t Bq Er EPROTONOSUPPORT Protocol not supported.
t Bq Er ESOCKTNOSUPPORT Socket type not supported.
t Bq Er EOPNOTSUPP Operation not supported.
t Bq Er EPFNOSUPPORT Protocol family not supported.
t Bq Er EAFNOSUPPORT Address family not supported by protocol family.
t Bq Er EADDRINUSE Address already in use.
t Bq Er EADDRNOTAVAIL Cannot assign requested address.
t Bq Er ENETDOWN Network is down.
t Bq Er ENETUNREACH Network is unreachable.
t Bq Er ENETRESET Network dropped connection on reset.
t Bq Er ECONNABORTED Software causes connection abort.
t Bq Er ENOBUFS No buffer space available.
t Bq Er EISCONN Socket is already connected.
t Bq Er ENOTCONN Socket is not connected.
t Bq Er ESHUTDOWN Cannot send after socket shutdown.
t Bq Er ETOOMANYREFS Too many references: cannot splice.
t Bq Er ETIMEDOUT Operation timed out.
t Bq Er ECONNREFUSED Connection refused.
t Bq Er ELOOP Too many levels of symbolic links.
t Bq Er ENAMETOOLONG File name too long.
t Bq Er EHOSTDOWN Host is down.
t Bq Er EHOSTUNREACH No route to host.
t Bq Er ENOTEMPTY Directory not empty.
t Bq Er EPROCLIM Too many processes.
t Bq Er EUSERS Too many users.
t Bq Er EDQUOT Disc quota exceeded.
t Bq Er ESTALE Stale NFS file handle.
t Bq Er EREMOTE Too many levels of remote in path.
t Bq Er EBADRPC RPC struct is bad.
t Bq Er ERPCMISMATCH RPC version wrong.
t Bq Er EPROGUNAVAIL RPC program not available.
t Bq Er EPROGMISMATCH Program version wrong.
t Bq Er EPROCUNAVAIL Bad procedure for program.
t Bq Er ENOLCK No locks available.
t Bq Er ENOSYS Function not implemented.
t Bq Er EFTYPE Inappropriate file type or format.
t Bq Er EAUTH Authentication error.
t Bq Er ENEEDAUTH Need authenticator.
t Bq Er EIDRM Identifier removed.
t Bq Er ENOMSG No message of desired type.
t Bq Er EOVERFLOW Value too large to be stored in data type.
t Bq Er ECANCELED Operation canceled.
t Bq Er EILSEQ Illegal byte sequence.
t Bq Er ENOATTR Attribute not found.
t 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 .
p Some other common .Sx HISTORY section examples are:
p The .Nm manual page example first appeared in x 4.4 .
p 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.