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