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