share/examples/mdoc/example.9

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