share/examples/mdoc/example.9

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