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