1.\" 2.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD 3.\" 4.\" Copyright (c) [year] [your name] 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD$ 28.\" 29.\" Note: The date here should be updated whenever a non-trivial 30.\" change is made to the manual page. 31.Dd September 27, 2006 32.Dt EXAMPLE 9 33.Os 34.Sh NAME 35.Nm example 36.Nd "example kernel interface manual page" 37.Sh SYNOPSIS 38.In sys/example.h 39.Ft int 40.Fn example "char *ptr" "int mode" 41.Sh DESCRIPTION 42This is an example manual page for the 43.Fn example 44kernel function. 45It is intended that this example can be used as a template 46when writing a new manual page. 47.Pp 48The 49.Fn example 50function takes two arguments: 51.Fa ptr 52and 53.Fa mode . 54The argument 55.Fa mode 56may have one of the following values: 57.Bl -tag -width ".Dv EXAMPLE_ONE" 58.It Dv EXAMPLE_ONE 59First example of a defined variable. 60.Dv EXAMPLE_ONE 61is described below. 62.It Dv EXAMPLE_TWO 63Second example. 64.El 65.Pp 66The above values are defined in 67.In example.h 68as follows: 69.Bd -literal 70#define EXAMPLE_ONE 1 71#define EXAMPLE_TWO 2 72.Ed 73.Sh IMPLEMENTATION NOTES 74The 75.Fn example 76function is not actually implemented. 77.Sh LOCKING 78The 79.Va example_lock 80lock must be held before 81.Fn example 82is called. 83.Pp 84Since 85.Va example_lock 86is a 87.Xr mutex 9 , 88no sleepable locks (i.e., 89.Xr sx 9 90locks) can be acquired in 91.Fn example . 92.Sh RETURN VALUES 93The 94.Fn example 95function returns the value 0 if successful; 96otherwise one of the values listed in the 97.Sx ERRORS 98section is returned, to indicate the error. 99.Sh EXAMPLES 100.Bd -literal 101 int error; 102 103 mtx_lock(&example_lock); 104 if ((error = example(NULL, EXAMPLE_ONE)) != 0) { 105 mtx_unlock(&example_lock); 106 return (error); 107 } 108 mtx_unlock(&example_lock); 109.Ed 110.Sh COMPATIBILITY 111The 112.Fn example 113function has no known compatibility issues. 114.Sh ERRORS 115.\" Delete any errno's that are not returned by your 116.\" function or system call and then tailor the 117.\" remaining text as needed. 118The 119.Fn example 120function will fail if: 121.Bl -tag -width Er 122.It Bq Er EPERM 123Operation not permitted. 124.It Bq Er ENOENT 125No such file or directory. 126.It Bq Er ESRCH 127No such process. 128.It Bq Er EINTR 129Interrupted system call. 130.It Bq Er EIO 131Input/output error. 132.It Bq Er ENXIO 133Device not configured. 134.It Bq Er E2BIG 135Argument list too long. 136.It Bq Er ENOEXEC 137Exec format error. 138.It Bq Er EBADF 139Bad file descriptor. 140.It Bq Er ECHILD 141No child processes. 142.It Bq Er EDEADLK 143Resource deadlock avoided. 144.It Bq Er ENOMEM 145Cannot allocate memory. 146.It Bq Er EACCES 147Permission denied. 148.It Bq Er EFAULT 149Bad address. 150.It Bq Er ENOTBLK 151Block device required. 152.It Bq Er EBUSY 153Device busy. 154.It Bq Er EEXIST 155File exists. 156.It Bq Er EXDEV 157Cross-device link. 158.It Bq Er ENODEV 159Operation not supported by device. 160.It Bq Er ENOTDIR 161Not a directory. 162.It Bq Er EISDIR 163Is a directory. 164.It Bq Er EINVAL 165Invalid argument. 166.It Bq Er ENFILE 167Too many open files in system. 168.It Bq Er EMFILE 169Too many open files. 170.It Bq Er ENOTTY 171Inappropriate ioctl for device. 172.It Bq Er ETXTBSY 173Text file busy. 174.It Bq Er EFBIG 175File too large. 176.It Bq Er ENOSPC 177No space left on device. 178.It Bq Er ESPIPE 179Illegal seek. 180.It Bq Er EROFS 181Read-only file system. 182.It Bq Er EMLINK 183Too many links. 184.It Bq Er EPIPE 185Broken pipe. 186.It Bq Er EDOM 187Numerical argument out of domain. 188.It Bq Er ERANGE 189Result too large. 190.It Bq Er EAGAIN 191Resource temporarily unavailable. 192.It Bq Er EWOULDBLOCK 193Operation would block. 194.It Bq Er EINPROGRESS 195Operation now in progress. 196.It Bq Er EALREADY 197Operation already in progress. 198.It Bq Er ENOTSOCK 199Socket operation on non-socket. 200.It Bq Er EDESTADDRREQ 201Destination address required. 202.It Bq Er EMSGSIZE 203Message too long. 204.It Bq Er EPROTOTYPE 205Protocol wrong type for socket. 206.It Bq Er ENOPROTOOPT 207Protocol not available. 208.It Bq Er EPROTONOSUPPORT 209Protocol not supported. 210.It Bq Er ESOCKTNOSUPPORT 211Socket type not supported. 212.It Bq Er EOPNOTSUPP 213Operation not supported. 214.It Bq Er EPFNOSUPPORT 215Protocol family not supported. 216.It Bq Er EAFNOSUPPORT 217Address family not supported by protocol family. 218.It Bq Er EADDRINUSE 219Address already in use. 220.It Bq Er EADDRNOTAVAIL 221Cannot assign requested address. 222.It Bq Er ENETDOWN 223Network is down. 224.It Bq Er ENETUNREACH 225Network is unreachable. 226.It Bq Er ENETRESET 227Network dropped connection on reset. 228.It Bq Er ECONNABORTED 229Software causes connection abort. 230.It Bq Er ENOBUFS 231No buffer space available. 232.It Bq Er EISCONN 233Socket is already connected. 234.It Bq Er ENOTCONN 235Socket is not connected. 236.It Bq Er ESHUTDOWN 237Cannot send after socket shutdown. 238.It Bq Er ETOOMANYREFS 239Too many references: cannot splice. 240.It Bq Er ETIMEDOUT 241Operation timed out. 242.It Bq Er ECONNREFUSED 243Connection refused. 244.It Bq Er ELOOP 245Too many levels of symbolic links. 246.It Bq Er ENAMETOOLONG 247File name too long. 248.It Bq Er EHOSTDOWN 249Host is down. 250.It Bq Er EHOSTUNREACH 251No route to host. 252.It Bq Er ENOTEMPTY 253Directory not empty. 254.It Bq Er EPROCLIM 255Too many processes. 256.It Bq Er EUSERS 257Too many users. 258.It Bq Er EDQUOT 259Disc quota exceeded. 260.It Bq Er ESTALE 261Stale NFS file handle. 262.It Bq Er EREMOTE 263Too many levels of remote in path. 264.It Bq Er EBADRPC 265RPC struct is bad. 266.It Bq Er ERPCMISMATCH 267RPC version wrong. 268.It Bq Er EPROGUNAVAIL 269RPC program not available. 270.It Bq Er EPROGMISMATCH 271Program version wrong. 272.It Bq Er EPROCUNAVAIL 273Bad procedure for program. 274.It Bq Er ENOLCK 275No locks available. 276.It Bq Er ENOSYS 277Function not implemented. 278.It Bq Er EFTYPE 279Inappropriate file type or format. 280.It Bq Er EAUTH 281Authentication error. 282.It Bq Er ENEEDAUTH 283Need authenticator. 284.It Bq Er EIDRM 285Identifier removed. 286.It Bq Er ENOMSG 287No message of desired type. 288.It Bq Er EOVERFLOW 289Value too large to be stored in data type. 290.It Bq Er ECANCELED 291Operation canceled. 292.It Bq Er EILSEQ 293Illegal byte sequence. 294.It Bq Er ENOATTR 295Attribute not found. 296.It Bq Er EDOOFUS 297Programming error. 298.El 299.Sh SEE ALSO 300.Xr example 1 , 301.Xr example 3 , 302.Xr example 4 , 303.Xr mdoc 7 , 304.Xr mutex 9 305.Rs 306.%A "A. B. Author" 307.%T "Example RFC Title" 308.%O RFC0000 309.Re 310.Rs 311.%A "A. B. Author" 312.%B "Example Book Title" 313.%O ISBN-0-000-00000-0 314.Re 315.Rs 316.%A "A. B. Author" 317.%D "January 1997" 318.%J "Example Journal Name" 319.%T "Example Article Title" 320.Re 321.Sh HISTORY 322The 323.Nm 324manual page example first appeared in 325.Fx 6.0 . 326.Pp 327Some other common 328.Sx HISTORY 329section examples are: 330.Pp 331The 332.Nm 333manual page example first appeared in 334.Bx 4.4 . 335.Pp 336The 337.Nm 338manual page example first appeared in 339.At v6 . 340.Sh AUTHORS 341This 342manual page was written by 343.An Giorgos Keramidas Aq Mt keramida@FreeBSD.org . 344.Sh BUGS 345The actual code for this function is vaporware. 346