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