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 Ohttp://wafu.netgate.net/tama/unix/indexe.htmlTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
| 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 Ohttp://wafu.netgate.net/tama/unix/indexe.htmlTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
|
113returns zero, the variable will be unset. The predefined function
114.Fa env_nounset
115may be used to prevent a variable being unset.
116.El
117.Sh STANDARD LIBRARY SUPPORT
118.Bl -hang -width 10n
119.It Fn "int getopt" "int argc" "char * const *argv" "cont char *optstring"
120.It Fn "long strtol" "const char *nptr" "char **endptr" "int base"
121.It Fn "void srandom" "unsigned long seed"
122.It Fn "unsigned long random" "void"
123.It Fn "char *strerror" "int error"
124.Pp
125Returns error messages for the subset of errno values supported by
126.Nm No .
127.It Fn "assert" "expression"
128.Pp
129Requires
130.Fd #include <assert.h>
131.It Fn "int setjmp" "jmp_buf env"
132.It Fn "void longjmp" "jmp_buf env" "int val"
133.Pp
134Defined as
135.Fn _setjmp
136and
137.Fn _lonjmp
138respectively as there is no signal state to manipulate. Requires
139.Fd #include <setjmp.h>
140.El
141.Sh CHARACTER I/O
142.Bl -hang -width 10n
143.It Fn "void gets" "char *buf"
144.Pp
145Read characters from the console into
146.Fa buf .
147All of the standard cautions apply to this function.
148.It Fn "void ngets" "char *buf" "size_t size"
149.Pp
150Read at most
151.Fa size
152- 1 characters from the console into
153.Fa buf .
154If
155.Fa size
156is less than 1, the function's behaviour is as for
157.Fn gets .
158.It Fn "int fgetstr" "char *buf" "int size" "int fd"
159.Pp
160Read a line of at most
161.Fa size
162characters into
163.Fa buf .
164Line terminating characters are stripped, and the buffer is always nul
165terminated. Returns the number of characters in
166.Fa buf
167if successful, or -1 if a read error occurs.
168.It Fn "int printf" "const char *fmt" "..."
169.It Fn "void vprintf" "const char *fmt" "va_list ap"
170.It Fn "int sprintf" "char *buf" "const char *fmt" "..."
171.It Fn "void vsprintf" "char *buf" "const char *fmt" "va_list ap"
172.Pp
173The *printf functions implement a subset of the standard
174.Fn printf
175family functionality and some extensions. The following standard conversions
176are supported: c,d,n,o,p,s,u,x. The following modifiers are supported:
177+,-,#,*,0,field width,precision,l.
178.Pp
179The
180.Li b
181conversion is provided to decode error registers. Its usage is:
182.Pp
183.Bd -offset indent
184printf(
185.Qq reg=%b\en ,
186regval,
187.Qq <base><arg>*
188);
189.Ed
190
191where <base> is the output expressed as a control character, eg. \e10 gives
192octal, \e20 gives hex. Each <arg> is a sequence of characters, the first of
193which gives the bit number to be inspected (origin 1) and the next characters
194(up to a character less than 32) give the text to be displayed if the bit is set.
195Thus
196.Pp
197.Bd -offset indent
198printf(
199.Qq reg=%b\en
2003
201.Qq \e10\e2BITTWO\e1BITONE\en
202);
203.Ed
204
205would give the output
206.Pp
207.Bd -offset indent
208reg=3<BITTWO,BITONE>
209.Ed
210.Pp
211The
212.Li D
213conversion provides a hexdump facility, eg.
214.Pp
215.Bd -offset indent -literal
216printf(
217.Qq %6D ,
218ptr,
219.Qq \:
220); gives
221.Qq XX:XX:XX:XX:XX:XX
222.Ed
223.Bd -offset indent -literal
224printf(
225.Qq %*D ,
226len,
227ptr,
228.Qq "\ "
229); gives
230.Qq XX XX XX ...
231.Ed
232.El
233.Sh CHARACTER TESTS AND CONVERSIONS
234.Bl -hang -width 10n
235.It Fn "int isupper" "int c"
236.It Fn "int islower" "int c"
237.It Fn "int isspace" "int c"
238.It Fn "int isdigit" "int c"
239.It Fn "int isxdigit" "int c"
240.It Fn "int isascii" "int c"
241.It Fn "int isalpha" "int c"
242.It Fn "int toupper" "int c"
243.It Fn "int tolower" "int c"
244.El
245.Sh FILE I/O
246.Bl -hang -width 10n
247.It Fn "int open" "const char *path" "int flags"
248.Pp
249Similar to the behaviour as specified in
250.Xr open 2 ,
251except that file creation is not supported, so the mode parameter is not
252required. The
253.Fa flags
254argument may be one of O_RDONLY, O_WRONLY and O_RDWR (although no filesystems
255currently support writing).
256.It Fn "int close" "int fd"
257.It Fn "void closeall" "void"
258.Pp
259Close all open files.
260.It Fn "ssize_t read" "int fd" "void *buf" "size_t len"
261.It Fn "ssize_t write" "int fd" "void *buf" "size_t len"
262.Pp
263(No filesystems currently support writing.)
264.It Fn "off_t lseek" "int fd" "off_t offset" "int whence"
265.Pp
266Files being automatically uncompressed during reading cannot seek backwards
267from the current point.
268.It Fn "int stat" "const char *path" "struct stat *sb"
269.It Fn "int fstat" "int fd" "struct stat *sb"
270.Pp
271The
272.Fn stat
273and
274.Fn fstat
275functions only fill out the following fields in the
276.Fa sb
277structure: st_mode,st_nlink,st_uid,st_gid,st_size. The
278.Nm tftp
279filesystem cannot provide meaningful values for this call, and the
280.Nm cd9660
281filesystem always reports files having uid/gid of zero.
282.El
283.Sh PAGER
284.Nm
285supplies a simple internal pager to ease reading the output of large commands.
286.Bl -hang -width 10n
287.It Fn "void pager_open"
288.Pp
289Initialises the pager and tells it that the next line output will be the top of the
290display. The environment variable LINES is consulted to determine the number of
291lines to be displayed before pausing.
292.It Fn "void pager_close" "void"
293.Pp
294Closes the pager.
295.It Fn "void pager_output" "char *lines"
296.Pp
297Sends the lines in the nul-terminated buffer at
298.Fa lines
299to the pager. Newline characters are counted in order to determine the number
300of lines being output (wrapped lines are not accounted for).
301.Fn pager_output
302will return zero when all of the lines have been output, or nonzero if the
303display was paused and the user elected to quit.
304.It Fn "int pager_file" "char *fname"
305.Pp
306Attempts to open and display the file
307.Fa fname.
308 Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading.
309.El
310.Sh MISC
311.Bl -hang -width 10n
312.It Fn "void twiddle" "void"
313.Pp
314Successive calls emit the characters in the sequence |,/,-,\\ followed by a
315backspace in order to provide reassurance to the user.
316.El
317.Sh REQUIRED LOW-LEVEL SUPPORT
318The following resources are consumed by
319.Nm
320- stack, heap, console and devices.
321.Pp
322The stack must be established before
323.Nm
324functions can be invoked. Stack requirements vary depending on the functions
325and filesystems used by the consumer and the support layer functions detailed
326below.
327.Pp
328The heap must be established before calling
329.Fn alloc
330or
331.Fn open
332by calling
333.Fn setheap .
334Heap usage will vary depending on the number of simultaneously open files,
335as well as client behaviour. Automatic decompression will allocate more
336than 64K of data per open file.
337.Pp
338Console access is performed via the
339.Fn getchar ,
340.Fn putchar
341and
342.Fn ischar
343functions detailed below.
344.Pp
345Device access is initiated via
346.Fn devopen
347and is performed through the
348.Fn dv_strategy ,
349.Fn dv_ioctl
350and
351.Fn dv_close
352functions in the device switch structure that
353.Fn devopen
354returns.
355.Pp
356The consumer must provide the following support functions:
357.Bl -hang -width 10n
358.It Fn "int getchar" "void"
359.Pp
360Return a character from the console, used by
361.Fn gets ,
362.Fn ngets
363and pager functions.
364.It Fn "int ischar" "void"
365.Pp
366Returns nonzero if a character is waiting from the console.
367.It Fn "void putchar" "int"
368.Pp
369Write a character to the console, used by
370.Fn gets ,
371.Fn ngets ,
372.Fn *printf ,
373.Fn panic
374and
375.Fn twiddle
376and thus by many other functions for debugging and informational output.
377.It Fn "int devopen" "struct open_file *of" "const char *name" "char **file"
378.Pp
379Open the appropriate device for the file named in
380.Fa name ,
381returning in
382.Fa file
383a pointer to the remaining body of
384.Fa name
385which does not refer to the device. The
386.Va f_dev
387field in
388.Fa of
389will be set to point to the
390.Dv devsw
391structure for the opened device if successful. Device identifiers must
392always precede the path component, but may otherwise be arbitrarily formatted.
393Used by
394.Fn open
395and thus for all device-related I/O.
396.It Fn "int devclose" "struct open_file *of"
397Close the device allocated for
398.Fa of .
399The device driver itself will already have been called for the close; this call
400should clean up any allocation made by devopen only.
401.It Fn "void panic" "const char *msg" "..."
402.Pp
403Signal a fatal and unrecoverable error condition. The
404.Fa msg ...
405arguments are as for
406.Fn printf .
407.El
408.Sh INTERNAL FILESYSTEMS
409Internal filesystems are enabled by the consumer exporting the array
410.Dv struct fs_ops *file_system[], which should be initialised with pointers
411to
412.Dv struct fs_ops
413structures. The following filesystem handlers are supplied by
414.Nm No ,
415the consumer may supply other filesystems of their own:
416.Bl -hang -width "cd9660_fsops "
417.It ufs_fsops
418The BSD UFS.
419.It tftp_fsops
420File access via TFTP.
421.It nfs_fsops
422File access via NFS.
423.It cd9660_fsops
424ISO 9660 (CD-ROM) filesystem.
425.It zipfs_fsops
| 114returns zero, the variable will be unset. The predefined function
115.Fa env_nounset
116may be used to prevent a variable being unset.
117.El
118.Sh STANDARD LIBRARY SUPPORT
119.Bl -hang -width 10n
120.It Fn "int getopt" "int argc" "char * const *argv" "cont char *optstring"
121.It Fn "long strtol" "const char *nptr" "char **endptr" "int base"
122.It Fn "void srandom" "unsigned long seed"
123.It Fn "unsigned long random" "void"
124.It Fn "char *strerror" "int error"
125.Pp
126Returns error messages for the subset of errno values supported by
127.Nm No .
128.It Fn "assert" "expression"
129.Pp
130Requires
131.Fd #include <assert.h>
132.It Fn "int setjmp" "jmp_buf env"
133.It Fn "void longjmp" "jmp_buf env" "int val"
134.Pp
135Defined as
136.Fn _setjmp
137and
138.Fn _lonjmp
139respectively as there is no signal state to manipulate. Requires
140.Fd #include <setjmp.h>
141.El
142.Sh CHARACTER I/O
143.Bl -hang -width 10n
144.It Fn "void gets" "char *buf"
145.Pp
146Read characters from the console into
147.Fa buf .
148All of the standard cautions apply to this function.
149.It Fn "void ngets" "char *buf" "size_t size"
150.Pp
151Read at most
152.Fa size
153- 1 characters from the console into
154.Fa buf .
155If
156.Fa size
157is less than 1, the function's behaviour is as for
158.Fn gets .
159.It Fn "int fgetstr" "char *buf" "int size" "int fd"
160.Pp
161Read a line of at most
162.Fa size
163characters into
164.Fa buf .
165Line terminating characters are stripped, and the buffer is always nul
166terminated. Returns the number of characters in
167.Fa buf
168if successful, or -1 if a read error occurs.
169.It Fn "int printf" "const char *fmt" "..."
170.It Fn "void vprintf" "const char *fmt" "va_list ap"
171.It Fn "int sprintf" "char *buf" "const char *fmt" "..."
172.It Fn "void vsprintf" "char *buf" "const char *fmt" "va_list ap"
173.Pp
174The *printf functions implement a subset of the standard
175.Fn printf
176family functionality and some extensions. The following standard conversions
177are supported: c,d,n,o,p,s,u,x. The following modifiers are supported:
178+,-,#,*,0,field width,precision,l.
179.Pp
180The
181.Li b
182conversion is provided to decode error registers. Its usage is:
183.Pp
184.Bd -offset indent
185printf(
186.Qq reg=%b\en ,
187regval,
188.Qq <base><arg>*
189);
190.Ed
191
192where <base> is the output expressed as a control character, eg. \e10 gives
193octal, \e20 gives hex. Each <arg> is a sequence of characters, the first of
194which gives the bit number to be inspected (origin 1) and the next characters
195(up to a character less than 32) give the text to be displayed if the bit is set.
196Thus
197.Pp
198.Bd -offset indent
199printf(
200.Qq reg=%b\en
2013
202.Qq \e10\e2BITTWO\e1BITONE\en
203);
204.Ed
205
206would give the output
207.Pp
208.Bd -offset indent
209reg=3<BITTWO,BITONE>
210.Ed
211.Pp
212The
213.Li D
214conversion provides a hexdump facility, eg.
215.Pp
216.Bd -offset indent -literal
217printf(
218.Qq %6D ,
219ptr,
220.Qq \:
221); gives
222.Qq XX:XX:XX:XX:XX:XX
223.Ed
224.Bd -offset indent -literal
225printf(
226.Qq %*D ,
227len,
228ptr,
229.Qq "\ "
230); gives
231.Qq XX XX XX ...
232.Ed
233.El
234.Sh CHARACTER TESTS AND CONVERSIONS
235.Bl -hang -width 10n
236.It Fn "int isupper" "int c"
237.It Fn "int islower" "int c"
238.It Fn "int isspace" "int c"
239.It Fn "int isdigit" "int c"
240.It Fn "int isxdigit" "int c"
241.It Fn "int isascii" "int c"
242.It Fn "int isalpha" "int c"
243.It Fn "int toupper" "int c"
244.It Fn "int tolower" "int c"
245.El
246.Sh FILE I/O
247.Bl -hang -width 10n
248.It Fn "int open" "const char *path" "int flags"
249.Pp
250Similar to the behaviour as specified in
251.Xr open 2 ,
252except that file creation is not supported, so the mode parameter is not
253required. The
254.Fa flags
255argument may be one of O_RDONLY, O_WRONLY and O_RDWR (although no filesystems
256currently support writing).
257.It Fn "int close" "int fd"
258.It Fn "void closeall" "void"
259.Pp
260Close all open files.
261.It Fn "ssize_t read" "int fd" "void *buf" "size_t len"
262.It Fn "ssize_t write" "int fd" "void *buf" "size_t len"
263.Pp
264(No filesystems currently support writing.)
265.It Fn "off_t lseek" "int fd" "off_t offset" "int whence"
266.Pp
267Files being automatically uncompressed during reading cannot seek backwards
268from the current point.
269.It Fn "int stat" "const char *path" "struct stat *sb"
270.It Fn "int fstat" "int fd" "struct stat *sb"
271.Pp
272The
273.Fn stat
274and
275.Fn fstat
276functions only fill out the following fields in the
277.Fa sb
278structure: st_mode,st_nlink,st_uid,st_gid,st_size. The
279.Nm tftp
280filesystem cannot provide meaningful values for this call, and the
281.Nm cd9660
282filesystem always reports files having uid/gid of zero.
283.El
284.Sh PAGER
285.Nm
286supplies a simple internal pager to ease reading the output of large commands.
287.Bl -hang -width 10n
288.It Fn "void pager_open"
289.Pp
290Initialises the pager and tells it that the next line output will be the top of the
291display. The environment variable LINES is consulted to determine the number of
292lines to be displayed before pausing.
293.It Fn "void pager_close" "void"
294.Pp
295Closes the pager.
296.It Fn "void pager_output" "char *lines"
297.Pp
298Sends the lines in the nul-terminated buffer at
299.Fa lines
300to the pager. Newline characters are counted in order to determine the number
301of lines being output (wrapped lines are not accounted for).
302.Fn pager_output
303will return zero when all of the lines have been output, or nonzero if the
304display was paused and the user elected to quit.
305.It Fn "int pager_file" "char *fname"
306.Pp
307Attempts to open and display the file
308.Fa fname.
309 Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading.
310.El
311.Sh MISC
312.Bl -hang -width 10n
313.It Fn "void twiddle" "void"
314.Pp
315Successive calls emit the characters in the sequence |,/,-,\\ followed by a
316backspace in order to provide reassurance to the user.
317.El
318.Sh REQUIRED LOW-LEVEL SUPPORT
319The following resources are consumed by
320.Nm
321- stack, heap, console and devices.
322.Pp
323The stack must be established before
324.Nm
325functions can be invoked. Stack requirements vary depending on the functions
326and filesystems used by the consumer and the support layer functions detailed
327below.
328.Pp
329The heap must be established before calling
330.Fn alloc
331or
332.Fn open
333by calling
334.Fn setheap .
335Heap usage will vary depending on the number of simultaneously open files,
336as well as client behaviour. Automatic decompression will allocate more
337than 64K of data per open file.
338.Pp
339Console access is performed via the
340.Fn getchar ,
341.Fn putchar
342and
343.Fn ischar
344functions detailed below.
345.Pp
346Device access is initiated via
347.Fn devopen
348and is performed through the
349.Fn dv_strategy ,
350.Fn dv_ioctl
351and
352.Fn dv_close
353functions in the device switch structure that
354.Fn devopen
355returns.
356.Pp
357The consumer must provide the following support functions:
358.Bl -hang -width 10n
359.It Fn "int getchar" "void"
360.Pp
361Return a character from the console, used by
362.Fn gets ,
363.Fn ngets
364and pager functions.
365.It Fn "int ischar" "void"
366.Pp
367Returns nonzero if a character is waiting from the console.
368.It Fn "void putchar" "int"
369.Pp
370Write a character to the console, used by
371.Fn gets ,
372.Fn ngets ,
373.Fn *printf ,
374.Fn panic
375and
376.Fn twiddle
377and thus by many other functions for debugging and informational output.
378.It Fn "int devopen" "struct open_file *of" "const char *name" "char **file"
379.Pp
380Open the appropriate device for the file named in
381.Fa name ,
382returning in
383.Fa file
384a pointer to the remaining body of
385.Fa name
386which does not refer to the device. The
387.Va f_dev
388field in
389.Fa of
390will be set to point to the
391.Dv devsw
392structure for the opened device if successful. Device identifiers must
393always precede the path component, but may otherwise be arbitrarily formatted.
394Used by
395.Fn open
396and thus for all device-related I/O.
397.It Fn "int devclose" "struct open_file *of"
398Close the device allocated for
399.Fa of .
400The device driver itself will already have been called for the close; this call
401should clean up any allocation made by devopen only.
402.It Fn "void panic" "const char *msg" "..."
403.Pp
404Signal a fatal and unrecoverable error condition. The
405.Fa msg ...
406arguments are as for
407.Fn printf .
408.El
409.Sh INTERNAL FILESYSTEMS
410Internal filesystems are enabled by the consumer exporting the array
411.Dv struct fs_ops *file_system[], which should be initialised with pointers
412to
413.Dv struct fs_ops
414structures. The following filesystem handlers are supplied by
415.Nm No ,
416the consumer may supply other filesystems of their own:
417.Bl -hang -width "cd9660_fsops "
418.It ufs_fsops
419The BSD UFS.
420.It tftp_fsops
421File access via TFTP.
422.It nfs_fsops
423File access via NFS.
424.It cd9660_fsops
425ISO 9660 (CD-ROM) filesystem.
426.It zipfs_fsops
|