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