lib/libstand/libstand.3

   1 .\" Copyright (c) Michael Smith
   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/lib/libstand/libstand.3,v 1.5.2.11 2002/06/26 19:14:43 schweikh Exp $
  26 .\" $DragonFly: src/lib/libstand/libstand.3,v 1.7 2007/09/14 19:47:03 swildner Exp $
  27 .\"
  28 .Dd September 13, 2004
  29 .Dt LIBSTAND 3
  30 .Os
  31 .Sh NAME
  32 .Nm libstand
  33 .Nd support library for standalone executables
  34 .Sh LIBRARY
  35 .Lb libstand
  36 .Sh SYNOPSIS
  37 .In stand.h
  38 .Sh DESCRIPTION
  39 .Nm
  40 provides a set of supporting functions for standalone
  41 applications, mimicking where possible the standard
  42 .Bx
  43 programming
  44 environment.  The following sections group these functions by kind.
  45 Unless specifically described here, see the corresponding section 3
  46 manpages for the given functions.
  47 .Sh STRING FUNCTIONS
  48 String functions are available as documented in
  49 .Xr string 3
  50 and
  51 .Xr bstring 3 .
  52 .Sh MEMORY ALLOCATION
  53 .Bl -hang -width 10n
  54 .It Xo
  55 .Ft "void *"
  56 .Fn malloc "size_t size"
  57 .Xc
  58 .Pp
  59 Allocate
  60 .Fa size
  61 bytes of memory from the heap using a best-fit algorithm.
  62 .It Xo
  63 .Ft void
  64 .Fn free "void *ptr"
  65 .Xc
  66 .Pp
  67 Free the allocated object at
  68 .Fa ptr .
  69 .It Xo
  70 .Ft void
  71 .Fn setheap "void *start" "void *limit"
  72 .Xc
  73 .Pp
  74 Initialise the heap.  This function must be called before calling
  75 .Fn alloc
  76 for the first time.  The region between
  77 .Fa start
  78 and
  79 .Fa limit
  80 will be used for the heap; attempting to allocate beyond this will result
  81 in a panic.
  82 .It Xo
  83 .Ft "char *"
  84 .Fn sbrk "int junk"
  85 .Xc
  86 .Pp
  87 Provides the behaviour of
  88 .Fn sbrk 0 ,
  89 ie. returns the highest point that the heap has reached.  This value can
  90 be used during testing to determine the actual heap usage.  The
  91 .Fa junk
  92 argument is ignored.
  93 .El
  94 .Sh ENVIRONMENT
  95 A set of functions are provided for manipulating a flat variable space similar
  96 to the traditional shell-supported environment.  Major enhancements are support
  97 for set/unset hook functions.
  98 .Bl -hang -width 10n
  99 .It Xo
 100 .Ft "char *"
 101 .Fn getenv "const char *name"
 102 .Xc
 103 .It Xo
 104 .Ft int
 105 .Fn setenv "const char *name" "char *value" "int overwrite"
 106 .Xc
 107 .It Xo
 108 .Ft int
 109 .Fn putenv "const char *string"
 110 .Xc
 111 .It Xo
 112 .Ft int
 113 .Fn unsetenv "const char *name"
 114 .Xc
 115 .Pp
 116 These functions behave similarly to their standard library counterparts.
 117 .It Xo
 118 .Ft "struct env_var *"
 119 .Fn env_getenv "const char *name"
 120 .Xc
 121 .Pp
 122 Looks up a variable in the environment and returns its entire
 123 data structure.
 124 .It Xo
 125 .Ft int
 126 .Fn env_setenv "const char *name" "int flags" "char *value" "ev_sethook_t sethook" "ev_unsethook_t unsethook"
 127 .Xc
 128 .Pp
 129 Creates a new or sets an existing environment variable called
 130 .Fa name .
 131 If creating a new variable, the
 132 .Fa sethook
 133 and
 134 .Fa unsethook
 135 arguments may be specified.
 136 .Pp
 137 The set hook is invoked whenever an attempt
 138 is made to set the variable, unless the EV_NOHOOK flag is set.  Typically
 139 a set hook will validate the
 140 .Fa value
 141 argument, and then call
 142 .Fn env_setenv
 143 again with EV_NOHOOK set to actually save the value.  The predefined function
 144 .Fn env_noset
 145 may be specified to refuse all attempts to set a variable.
 146 .Pp
 147 The unset hook is invoked when an attempt is made to unset a variable.
 148 If it
 149 returns zero, the  variable will be unset.  The predefined function
 150 .Fa env_nounset
 151 may be used to prevent a variable being unset.
 152 .El
 153 .Sh STANDARD LIBRARY SUPPORT
 154 .Bl -hang -width 10n
 155 .It Xo
 156 .Ft int
 157 .Fn getopt "int argc" "char * const *argv" "const char *optstring"
 158 .Xc
 159 .It Xo
 160 .Ft long
 161 .Fn strtol "const char *nptr" "char **endptr" "int base"
 162 .Xc
 163 .It Xo
 164 .Ft void
 165 .Fn srandom "unsigned long seed"
 166 .Xc
 167 .It Xo
 168 .Ft "unsigned long"
 169 .Fn random void
 170 .Xc
 171 .It Xo
 172 .Ft "char *"
 173 .Fn strerror "int error"
 174 .Xc
 175 .Pp
 176 Returns error messages for the subset of
 177 .Va errno
 178 values supported by
 179 .Nm .
 180 .It Fn assert expression
 181 .Pp
 182 Requires
 183 .In assert.h
 184 .It Xo
 185 .Ft int
 186 .Fn setjmp "jmp_buf env"
 187 .Xc
 188 .It Xo
 189 .Ft void
 190 .Fn longjmp "jmp_buf env" "int val"
 191 .Xc
 192 .Pp
 193 Defined as
 194 .Fn _setjmp
 195 and
 196 .Fn _longjmp
 197 respectively as there is no signal state to manipulate.  Requires
 198 .In setjmp.h
 199 .El
 200 .Sh CHARACTER I/O
 201 .Bl -hang -width 10n
 202 .It Xo
 203 .Ft void
 204 .Fn gets "char *buf"
 205 .Xc
 206 .Pp
 207 Read characters from the console into
 208 .Fa buf .
 209 All of the standard cautions apply to this function.
 210 .It Xo
 211 .Ft void
 212 .Fn ngets "char *buf" "size_t size"
 213 .Xc
 214 .Pp
 215 Read at most
 216 .Fa size
 217 - 1 characters from the console into
 218 .Fa buf .
 219 If
 220 .Fa size
 221 is less than 1, the function's behaviour is as for
 222 .Fn gets .
 223 .It Xo
 224 .Ft int
 225 .Fn fgetstr "char *buf" "int size" "int fd"
 226 .Xc
 227 .Pp
 228 Read a line of at most
 229 .Fa size
 230 characters into
 231 .Fa buf .
 232 Line terminating characters are stripped, and the buffer is always nul
 233 terminated.  Returns the number of characters in
 234 .Fa buf
 235 if successful, or -1 if a read error occurs.
 236 .It Xo
 237 .Ft int
 238 .Fn printf "const char *fmt" "..."
 239 .Xc
 240 .It Xo
 241 .Ft void
 242 .Fn vprintf "const char *fmt" "va_list ap"
 243 .Xc
 244 .It Xo
 245 .Ft int
 246 .Fn sprintf "char *buf" "const char *fmt" "..."
 247 .Xc
 248 .It Xo
 249 .Ft void
 250 .Fn vsprintf "char *buf" "const char *fmt" "va_list ap"
 251 .Xc
 252 .Pp
 253 The *printf functions implement a subset of the standard
 254 .Fn printf
 255 family functionality and some extensions.  The following standard conversions
 256 are supported: c,d,n,o,p,s,u,x.  The following modifiers are supported:
 257 +,-,#,*,0,field width,precision,l.
 258 .Pp
 259 The
 260 .Li b
 261 conversion is provided to decode error registers.  Its usage is:
 262 .Pp
 263 .Bd -ragged -offset indent
 264 printf(
 265 .Qq reg=%b\en ,
 266 regval,
 267 .Qq <base><arg>*
 268 );
 269 .Ed
 270 .Pp
 271 where <base> is the output expressed as a control character, eg. \e10 gives
 272 octal, \e20 gives hex.  Each <arg> is a sequence of characters, the first of
 273 which gives the bit number to be inspected (origin 1) and the next characters
 274 (up to a character less than 32) give the text to be displayed if the bit is set.
 275 Thus
 276 .Pp
 277 .Bd -ragged -offset indent
 278 printf(
 279 .Qq reg=%b\en ,
 280 3,
 281 .Qq \e10\e2BITTWO\e1BITONE\en
 282 );
 283 .Ed
 284 .Pp
 285 would give the output
 286 .Pp
 287 .Bd -ragged -offset indent
 288 reg=3<BITTWO,BITONE>
 289 .Ed
 290 .Pp
 291 The
 292 .Li D
 293 conversion provides a hexdump facility, eg.
 294 .Pp
 295 .Bd -ragged -offset indent
 296 printf(
 297 .Qq %6D ,
 298 ptr,
 299 .Qq \&:
 300 );  gives
 301 .Qq XX:XX:XX:XX:XX:XX
 302 .Ed
 303 .Bd -ragged -offset indent
 304 printf(
 305 .Qq %*D ,
 306 len,
 307 ptr,
 308 .Qq "\ "
 309 );  gives
 310 .Qq XX XX XX ...
 311 .Ed
 312 .El
 313 .Sh CHARACTER TESTS AND CONVERSIONS
 314 .Bl -hang -width 10n
 315 .It Xo
 316 .Ft int
 317 .Fn isupper "int c"
 318 .Xc
 319 .It Xo
 320 .Ft int
 321 .Fn islower "int c"
 322 .Xc
 323 .It Xo
 324 .Ft int
 325 .Fn isspace "int c"
 326 .Xc
 327 .It Xo
 328 .Ft int
 329 .Fn isdigit "int c"
 330 .Xc
 331 .It Xo
 332 .Ft int
 333 .Fn isxdigit "int c"
 334 .Xc
 335 .It Xo
 336 .Ft int
 337 .Fn isascii "int c"
 338 .Xc
 339 .It Xo
 340 .Ft int
 341 .Fn isalpha "int c"
 342 .Xc
 343 .It Xo
 344 .Ft int
 345 .Fn toupper "int c"
 346 .Xc
 347 .It Xo
 348 .Ft int
 349 .Fn tolower "int c"
 350 .Xc
 351 .El
 352 .Sh FILE I/O
 353 .Bl -hang -width 10n
 354 .It Xo
 355 .Ft int
 356 .Fn open "const char *path" "int flags"
 357 .Xc
 358 .Pp
 359 Similar to the behaviour as specified in
 360 .Xr open 2 ,
 361 except that file creation is not supported, so the mode parameter is not
 362 required.  The
 363 .Fa flags
 364 argument may be one of O_RDONLY, O_WRONLY and O_RDWR (although no filesystems
 365 currently support writing).
 366 .It Xo
 367 .Ft int
 368 .Fn close "int fd"
 369 .Xc
 370 .It Xo
 371 .Ft void
 372 .Fn closeall void
 373 .Xc
 374 .Pp
 375 Close all open files.
 376 .It Xo
 377 .Ft ssize_t
 378 .Fn read "int fd" "void *buf" "size_t len"
 379 .Xc
 380 .It Xo
 381 .Ft ssize_t
 382 .Fn write "int fd" "void *buf" "size_t len"
 383 .Xc
 384 .Pp
 385 (No filesystems currently support writing.)
 386 .It Xo
 387 .Ft off_t
 388 .Fn lseek "int fd" "off_t offset" "int whence"
 389 .Xc
 390 .Pp
 391 Files being automatically uncompressed during reading cannot seek backwards
 392 from the current point.
 393 .It Xo
 394 .Ft int
 395 .Fn stat "const char *path" "struct stat *sb"
 396 .Xc
 397 .It Xo
 398 .Ft int
 399 .Fn fstat "int fd" "struct stat *sb"
 400 .Xc
 401 .Pp
 402 The
 403 .Fn stat
 404 and
 405 .Fn fstat
 406 functions only fill out the following fields in the
 407 .Fa sb
 408 structure: st_mode,st_nlink,st_uid,st_gid,st_size.  The
 409 .Nm tftp
 410 filesystem cannot provide meaningful values for this call, and the
 411 .Nm cd9660
 412 filesystem always reports files having uid/gid of zero.
 413 .El
 414 .Sh PAGER
 415 .Nm
 416 supplies a simple internal pager to ease reading the output of large commands.
 417 .Bl -hang -width 10n
 418 .It Xo
 419 .Ft void
 420 .Fn pager_open
 421 .Xc
 422 .Pp
 423 Initialises the pager and tells it that the next line output will be the top of the
 424 display.  The environment variable LINES is consulted to determine the number of
 425 lines to be displayed before pausing.
 426 .It Xo
 427 .Ft void
 428 .Fn pager_close void
 429 .Xc
 430 .Pp
 431 Closes the pager.
 432 .It Xo
 433 .Ft int
 434 .Fn pager_output "char *lines"
 435 .Xc
 436 .Pp
 437 Sends the lines in the nul-terminated buffer at
 438 .Fa lines
 439 to the pager.  Newline characters are counted in order to determine the number
 440 of lines being output (wrapped lines are not accounted for).
 441 .Fn pager_output
 442 will return zero when all of the lines have been output, or nonzero if the
 443 display was paused and the user elected to quit.
 444 .It Xo
 445 .Ft int
 446 .Fn pager_file "char *fname"
 447 .Xc
 448 .Pp
 449 Attempts to open and display the file
 450 .Fa fname .
 451 Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading.
 452 .El
 453 .Sh MISC
 454 .Bl -hang -width 10n
 455 .It Xo
 456 .Ft void
 457 .Fn twiddle void
 458 .Xc
 459 .Pp
 460 Successive calls emit the characters in the sequence |,/,-,\\ followed by a
 461 backspace in order to provide reassurance to the user.
 462 .El
 463 .Sh REQUIRED LOW-LEVEL SUPPORT
 464 The following resources are consumed by
 465 .Nm
 466 - stack, heap, console and devices.
 467 .Pp
 468 The stack must be established before
 469 .Nm
 470 functions can be invoked.  Stack requirements vary depending on the functions
 471 and filesystems used by the consumer and the support layer functions detailed
 472 below.
 473 .Pp
 474 The heap must be established before calling
 475 .Fn alloc
 476 or
 477 .Fn open
 478 by calling
 479 .Fn setheap .
 480 Heap usage will vary depending on the number of simultaneously open files,
 481 as well as client behaviour.  Automatic decompression will allocate more
 482 than 64K of data per open file.
 483 .Pp
 484 Console access is performed via the
 485 .Fn getchar ,
 486 .Fn putchar
 487 and
 488 .Fn ischar
 489 functions detailed below.
 490 .Pp
 491 Device access is initiated via
 492 .Fn devopen
 493 and is performed through the
 494 .Fn dv_strategy ,
 495 .Fn dv_ioctl
 496 and
 497 .Fn dv_close
 498 functions in the device switch structure that
 499 .Fn devopen
 500 returns.
 501 .Pp
 502 The consumer must provide the following support functions:
 503 .Bl -hang -width 10n
 504 .It Xo
 505 .Ft int
 506 .Fn getchar void
 507 .Xc
 508 .Pp
 509 Return a character from the console, used by
 510 .Fn gets ,
 511 .Fn ngets
 512 and pager functions.
 513 .It Xo
 514 .Ft int
 515 .Fn ischar void
 516 .Xc
 517 .Pp
 518 Returns nonzero if a character is waiting from the console.
 519 .It Xo
 520 .Ft void
 521 .Fn putchar int
 522 .Xc
 523 .Pp
 524 Write a character to the console, used by
 525 .Fn gets ,
 526 .Fn ngets ,
 527 .Fn *printf ,
 528 .Fn panic
 529 and
 530 .Fn twiddle
 531 and thus by many other functions for debugging and informational output.
 532 .It Xo
 533 .Ft int
 534 .Fn devopen "struct open_file *of" "const char *name" "char **file"
 535 .Xc
 536 .Pp
 537 Open the appropriate device for the file named in
 538 .Fa name ,
 539 returning in
 540 .Fa file
 541 a pointer to the remaining body of
 542 .Fa name
 543 which does not refer to the device.  The
 544 .Va f_dev
 545 field in
 546 .Fa of
 547 will be set to point to the
 548 .Vt devsw
 549 structure for the opened device if successful.  Device identifiers must
 550 always precede the path component, but may otherwise be arbitrarily formatted.
 551 Used by
 552 .Fn open
 553 and thus for all device-related I/O.
 554 .It Xo
 555 .Ft int
 556 .Fn devclose "struct open_file *of"
 557 .Xc
 558 Close the device allocated for
 559 .Fa of .
 560 The device driver itself will already have been called for the close; this call
 561 should clean up any allocation made by devopen only.
 562 .It Xo
 563 .Ft void
 564 .Fn panic "const char *msg" "..."
 565 .Xc
 566 .Pp
 567 Signal a fatal and unrecoverable error condition.  The
 568 .Fa msg ...
 569 arguments are as for
 570 .Fn printf .
 571 .El
 572 .Sh INTERNAL FILESYSTEMS
 573 Internal filesystems are enabled by the consumer exporting the array
 574 .Vt struct fs_ops *file_system[] ,
 575 which should be initialised with pointers
 576 to
 577 .Vt struct fs_ops
 578 structures.  The following filesystem handlers are supplied by
 579 .Nm ,
 580 the consumer may supply other filesystems of their own:
 581 .Bl -hang -width ".Va cd9660_fsops"
 582 .It Va ufs_fsops
 583 The
 584 .Bx
 585 UFS.
 586 .It Va ext2fs_fsops
 587 Linux ext2fs filesystem.
 588 .It Va tftp_fsops
 589 File access via TFTP.
 590 .It Va nfs_fsops
 591 File access via NFS.
 592 .It Va cd9660_fsops
 593 ISO 9660 (CD-ROM) filesystem.
 594 .It Va zipfs_fsops
 595 Stacked filesystem supporting gzipped files.
 596 When trying the zipfs filesystem,
 597 .Nm
 598 appends
 599 .Li .gz
 600 to the end of the filename, and then tries to locate the file using the other
 601 filesystems.  Placement of this filesystem in the
 602 .Va file_system[]
 603 array determines whether gzipped files will be opened in preference to non-gzipped
 604 files.  It is only possible to seek a gzipped file forwards, and
 605 .Fn stat
 606 and
 607 .Fn fstat
 608 on gzipped files will report an invalid length.
 609 .It Va bzipfs_fsops
 610 The same as
 611 .Va zipfs_fsops ,
 612 but for
 613 .Xr bzip2 1 Ns -compressed
 614 files.
 615 .El
 616 .Pp
 617 The array of
 618 .Vt struct fs_ops
 619 pointers should be terminated with a NULL.
 620 .Sh DEVICES
 621 Devices are exported by the supporting code via the array
 622 .Vt struct devsw *devsw[]
 623 which is a NULL terminated array of pointers to device switch structures.
 624 .Sh HISTORY
 625 .Nm
 626 contains contributions from many sources, including:
 627 .Bl -bullet -compact
 628 .It
 629 .Nm libsa
 630 from
 631 .Nx
 632 .It
 633 .Nm libc
 634 and
 635 .Nm libkern
 636 from
 637 .Fx 3.0 .
 638 .It
 639 .Nm zalloc
 640 from
 641 .An Matthew Dillon Aq dillon@backplane.com
 642 .El
 643 .Pp
 644 The reorganisation and port to
 645 .Fx 3.0 ,
 646 the environment functions and this manpage were written by
 647 .An Mike Smith Aq msmith@FreeBSD.org .
 648 .Sh BUGS
 649 The lack of detailed memory usage data is unhelpful.