Mateusz Piotrowski
83ac79599f
We live in the SPDX world now and our example manual pages should reflect that. Also, fix the order of the SPDX and copyright lines as per style(9). Reviewed by: ziaee MFC after: 3 days Differential Revision: https://reviews.freebsd.org/D53335
323 lines
6.2 KiB
Groff
323 lines
6.2 KiB
Groff
.\"
|
|
.\" Copyright (c) [year] [your name]
|
|
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause
|
|
.\"
|
|
.\" 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.
|