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 39provides a set of supporting functions for standalone 40applications, mimicking where possible the standard 41.Bx 42programming 43environment. 44The following sections group these functions by kind. 45Unless specifically described here, see the corresponding section 3 46manpages for the given functions. 47.Sh STRING FUNCTIONS 48String functions are available as documented in 49.Xr string 3 50and 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 59Allocate 60.Fa size 61bytes 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 67Free the allocated object at 68.Fa ptr . 69.It Xo 70.Ft void 71.Fn setheap "void *start" "void *limit" 72.Xc 73.Pp 74Initialise the heap. 75This function must be called before calling 76.Fn alloc 77for the first time. 78The region between 79.Fa start 80and 81.Fa limit 82will be used for the heap; attempting to allocate beyond this will result 83in a panic. 84.It Xo 85.Ft "char *" 86.Fn sbrk "intptr_t incr" 87.Xc 88.Pp 89Provides the behaviour of 90.Fn sbrk 0 , 91i.e.\& returns the highest point that the heap has reached. 92This value can 93be used during testing to determine the actual heap usage. 94The 95.Fa incr 96argument is ignored. 97.El 98.Sh ENVIRONMENT 99A set of functions are provided for manipulating a flat variable space similar 100to the traditional shell-supported environment. 101Major enhancements are support 102for 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 121These 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 127Looks up a variable in the environment and returns its entire 128data 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 134Creates a new or sets an existing environment variable called 135.Fa name . 136If creating a new variable, the 137.Fa sethook 138and 139.Fa unsethook 140arguments may be specified. 141.Pp 142The set hook is invoked whenever an attempt 143is made to set the variable, unless the 144.Dv EV_NOHOOK 145flag is set. 146Typically 147a set hook will validate the 148.Fa value 149argument, and then call 150.Fn env_setenv 151again with 152.Dv EV_NOHOOK 153set to actually save the value. 154The predefined function 155.Fn env_noset 156may be specified to refuse all attempts to set a variable. 157.Pp 158The unset hook is invoked when an attempt is made to unset a variable. 159If it 160returns zero, the variable will be unset. 161The predefined function 162.Fn env_nounset 163may 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 188Returns error messages for the subset of 189.Va errno 190values supported by 191.Nm . 192.It Fn assert expression 193.Pp 194Requires 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 205Defined as 206.Fn _setjmp 207and 208.Fn _longjmp 209respectively as there is no signal state to manipulate. 210Requires 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 220Read characters from the console into 221.Fa buf . 222All 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 228Read at most 229.Fa size 230- 1 characters from the console into 231.Fa buf . 232If 233.Fa size 234is 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 241Read a line of at most 242.Fa size Ns -1 243characters into 244.Fa buf . 245Line terminating characters are not stripped, 246and the buffer is always nul-terminated. 247Upon successful completion a pointer to the string is returned. 248If end-of-file occurs before any characters are read, 249NULL is returned and the buffer contents remain unchanged. 250If an error occurs, 251NULL 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 257Read a line of at most 258.Fa size 259characters into 260.Fa buf . 261Line terminating characters are stripped, and the buffer is always 262nul-terminated. 263Returns the number of characters in 264.Fa buf 265if 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 283The *printf functions implement a subset of the standard 284.Fn printf 285family functionality and some extensions. 286The following standard conversions 287are supported: 288.Cm c , d , n , o , p , s , u , x . 289The 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 338Similar to the behaviour as specified in 339.Xr open 2 , 340except that file creation is not supported, so the mode parameter is not 341required. 342The 343.Fa flags 344argument may be one of 345.Dv O_RDONLY , 346.Dv O_WRONLY 347and 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 359Close 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 375Files being automatically uncompressed during reading cannot seek backwards 376from 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 386The 387.Fn stat 388and 389.Fn fstat 390functions only fill out the following fields in the 391.Fa sb 392structure: 393.Fa st_mode , st_nlink , st_uid , st_gid , st_size . 394The 395.Nm tftp 396filesystem cannot provide meaningful values for this call, and the 397.Nm cd9660 398filesystem always reports files having uid/gid of zero. 399.El 400.Sh PAGER 401.Nm 402supplies 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 409Initialises the pager and tells it that the next line output will be the 410top of the display. 411The environment variable LINES is consulted to determine the number of 412lines to be displayed before pausing. 413.It Xo 414.Ft void 415.Fn pager_close void 416.Xc 417.Pp 418Closes the pager. 419.It Xo 420.Ft int 421.Fn pager_output "char *lines" 422.Xc 423.Pp 424Sends the lines in the nul-terminated buffer at 425.Fa lines 426to the pager. 427Newline characters are counted in order to determine the number 428of lines being output (wrapped lines are not accounted for). 429.Fn pager_output 430will return zero when all of the lines have been output, or nonzero if the 431display was paused and the user elected to quit. 432.It Xo 433.Ft int 434.Fn pager_file "char *fname" 435.Xc 436.Pp 437Attempts to open and display the file 438.Fa fname . 439Returns -1 on error, 0 at 440.Dv EOF , 441or 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 450Convert 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 459Successive calls emit the characters in the sequence |, /, -, \\ followed by a 460backspace in order to provide reassurance to the user. 461.El 462.Sh REQUIRED LOW-LEVEL SUPPORT 463The following resources are consumed by 464.Nm 465- stack, heap, console and devices. 466.Pp 467The stack must be established before 468.Nm 469functions can be invoked. 470Stack requirements vary depending on the functions 471and filesystems used by the consumer and the support layer functions detailed 472below. 473.Pp 474The heap must be established before calling 475.Fn alloc 476or 477.Fn open 478by calling 479.Fn setheap . 480Heap usage will vary depending on the number of simultaneously open files, 481as well as client behaviour. 482Automatic decompression will allocate more 483than 64K of data per open file. 484.Pp 485Console access is performed via the 486.Fn getchar , 487.Fn putchar 488and 489.Fn ischar 490functions detailed below. 491.Pp 492Device access is initiated via 493.Fn devopen 494and is performed through the 495.Fn dv_strategy , 496.Fn dv_ioctl 497and 498.Fn dv_close 499functions in the device switch structure that 500.Fn devopen 501returns. 502.Pp 503The 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 510Return a character from the console, used by 511.Fn gets , 512.Fn ngets 513and pager functions. 514.It Xo 515.Ft int 516.Fn ischar void 517.Xc 518.Pp 519Returns nonzero if a character is waiting from the console. 520.It Xo 521.Ft void 522.Fn putchar int 523.Xc 524.Pp 525Write a character to the console, used by 526.Fn gets , 527.Fn ngets , 528.Fn *printf , 529.Fn panic 530and 531.Fn twiddle 532and 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 538Open the appropriate device for the file named in 539.Fa name , 540returning in 541.Fa file 542a pointer to the remaining body of 543.Fa name 544which does not refer to the device. 545The 546.Va f_dev 547field in 548.Fa of 549will be set to point to the 550.Vt devsw 551structure for the opened device if successful. 552Device identifiers must 553always precede the path component, but may otherwise be arbitrarily formatted. 554Used by 555.Fn open 556and thus for all device-related I/O. 557.It Xo 558.Ft int 559.Fn devclose "struct open_file *of" 560.Xc 561.Pp 562Close the device allocated for 563.Fa of . 564The device driver itself will already have been called for the close; 565this call should clean up any allocation made by 566.Fn devopen 567only. 568.It Xo 569.Ft void 570.Fn panic "const char *msg" "..." 571.Xc 572.Pp 573Signal a fatal and unrecoverable error condition. 574The 575.Fa msg ... 576arguments are as for 577.Fn printf . 578.El 579.Sh INTERNAL FILESYSTEMS 580Internal filesystems are enabled by the consumer exporting the array 581.Vt struct fs_ops *file_system[] , 582which should be initialised with pointers 583to 584.Vt struct fs_ops 585structures. 586The following filesystem handlers are supplied by 587.Nm , 588the consumer may supply other filesystems of their own: 589.Bl -hang -width ".Va cd9660_fsops" 590.It Va ufs_fsops 591The 592.Bx 593.Xr UFS 5 . 594.It Va hammer1_fsops 595.Xr HAMMER 5 596filesystem. 597.It Va hammer2_fsops 598Hammer2 filesystem. 599.It Va ext2fs_fsops 600Linux ext2fs filesystem. 601.It Va msdos_fsops 602MS-DOS filesystem. 603.It Va tftp_fsops 604File access via TFTP. 605.It Va nfs_fsops 606File access via NFS. 607.It Va cd9660_fsops 608ISO 9660 (CD-ROM) filesystem. 609.It Va gzipfs_fsops 610Stacked filesystem supporting gzipped files. 611When trying the gzipfs filesystem, 612.Nm 613appends 614.Li .gz 615to the end of the filename, and then tries to locate the file using the other 616filesystems. 617Placement of this filesystem in the 618.Va file_system[] 619array determines whether gzipped files will be opened in preference to non-gzipped 620files. 621It is only possible to seek a gzipped file forwards, and 622.Fn stat 623and 624.Fn fstat 625on gzipped files will report an invalid length. 626.It Va bzipfs_fsops 627The same as 628.Va gzipfs_fsops , 629but for 630.Xr bzip2 1 Ns -compressed 631files. 632.El 633.Pp 634The array of 635.Vt struct fs_ops 636pointers should be terminated with a NULL. 637.Sh DEVICES 638Devices are exported by the supporting code via the array 639.Vt struct devsw *devsw[] 640which is a NULL terminated array of pointers to device switch structures. 641.Sh HISTORY 642.Nm 643contains contributions from many sources, including: 644.Bl -bullet -compact 645.It 646.Nm libsa 647from 648.Nx 649.It 650.Nm libc 651and 652.Nm libkern 653from 654.Fx 3.0 . 655.It 656.Nm zalloc 657from 658.An Matthew Dillon Aq Mt dillon@backplane.com 659.El 660.Pp 661The reorganisation and port to 662.Fx 3.0 , 663the environment functions and this manpage were written by 664.An Mike Smith Aq Mt msmith@FreeBSD.org . 665.Sh BUGS 666The lack of detailed memory usage data is unhelpful. 667