226a9d167b
The original Berkeley Software Distributions were made in the 1980's and 1990's. At that time, the Buenos Ares Convention of 1910 was in force in most of the countries in the Americas. It required an affirmative statement of rights reservation, typically using 'All Rights Reserved.' The Regents included this phrase in their copyright notices to invoke this treaty to ensure maximal copyright protection. In the 1990's, Latin America coutries ratifeid the Berne Convention on copyrights which prohibited them from requiring an affirmative statement to reserve the rights. When Nicaragua ratified in 2000, the Buenos Ares Convention of 1910 was effectively repealed. This made all the 'All Rights Reserved' phrases obsolete and legal deadweight most of the time, and certainly in the cases removed here. Since it's no longer required, and is in fact meaningless, core has decided to dropped it from the project's collection copyright and sample templates. It encourages other rights holders to do the same after consultation with their legal department. More see https://en.wikipedia.org/wiki/Buenos_Aires_Convention for more information. Approved by: core@ (emaste@, jhb@) Differential Review: https://reviews.freebsd.org/D15264
343 lines
7.5 KiB
Groff
343 lines
7.5 KiB
Groff
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" 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 ".Dv 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.
|