share/examples/mdoc/example.9

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