share/examples/mdoc/example.3

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