libsa.3 (f6b2a4291b85c8b8eadc131a054a7ac5416321fc) libsa.3 (45ad955714f8442a4485510de819755370a76af3)
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.

--- 10 unchanged lines hidden (view full) ---

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$
26.\"
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.

--- 10 unchanged lines hidden (view full) ---

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$
26.\"
27.Dd February 22, 2018
27.Dd September 9, 2022
28.Dt LIBSA 3
29.Os
30.Sh NAME
31.Nm libsa
32.Nd support library for standalone executables
33.Sh SYNOPSIS
34.In stand.h
35.Sh DESCRIPTION

--- 461 unchanged lines hidden (view full) ---

497.Pp
498Attempts to open and display the file
499.Fa fname .
500Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading.
501.El
502.Sh MISC
503.Bl -hang -width 10n
504.It Xo
28.Dt LIBSA 3
29.Os
30.Sh NAME
31.Nm libsa
32.Nd support library for standalone executables
33.Sh SYNOPSIS
34.In stand.h
35.Sh DESCRIPTION

--- 461 unchanged lines hidden (view full) ---

497.Pp
498Attempts to open and display the file
499.Fa fname .
500Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading.
501.El
502.Sh MISC
503.Bl -hang -width 10n
504.It Xo
505.Ft char *
506.Fn devformat "struct devdesc *"
507.Xc
508.Pp
509Format the specified device as a string.
510.It Xo
505.Ft void
506.Fn twiddle void
507.Xc
508.Pp
509Successive calls emit the characters in the sequence |,/,-,\\ followed by a
510backspace in order to provide reassurance to the user.
511.El
512.Sh REQUIRED LOW-LEVEL SUPPORT

--- 97 unchanged lines hidden (view full) ---

610.Xc
611.Pp
612Close the device allocated for
613.Fa of .
614The device driver itself will already have been called for the close; this call
615should clean up any allocation made by devopen only.
616.It Xo
617.Ft void
511.Ft void
512.Fn twiddle void
513.Xc
514.Pp
515Successive calls emit the characters in the sequence |,/,-,\\ followed by a
516backspace in order to provide reassurance to the user.
517.El
518.Sh REQUIRED LOW-LEVEL SUPPORT

--- 97 unchanged lines hidden (view full) ---

616.Xc
617.Pp
618Close the device allocated for
619.Fa of .
620The device driver itself will already have been called for the close; this call
621should clean up any allocation made by devopen only.
622.It Xo
623.Ft void
618.Fn abort
624.Fn __abort
619.Xc
620.Pp
621Calls
622.Fn panic
623with a fixed string.
624.It Xo
625.Ft void
626.Fn panic "const char *msg" "..."

--- 55 unchanged lines hidden (view full) ---

682.Pp
683The array of
684.Vt struct fs_ops
685pointers should be terminated with a NULL.
686.Sh DEVICES
687Devices are exported by the supporting code via the array
688.Vt struct devsw *devsw[]
689which is a NULL terminated array of pointers to device switch structures.
625.Xc
626.Pp
627Calls
628.Fn panic
629with a fixed string.
630.It Xo
631.Ft void
632.Fn panic "const char *msg" "..."

--- 55 unchanged lines hidden (view full) ---

688.Pp
689The array of
690.Vt struct fs_ops
691pointers should be terminated with a NULL.
692.Sh DEVICES
693Devices are exported by the supporting code via the array
694.Vt struct devsw *devsw[]
695which is a NULL terminated array of pointers to device switch structures.
696.Sh DRIVER INTERFACE
697The driver needs to provide a common set of entry points that are
698used by
699.Nm libsa
700to interface with the device.
701.Bd -literal
702struct devsw {
703 const char dv_name[DEV_NAMLEN];
704 int dv_type;
705 int (*dv_init)(void);
706 int (*dv_strategy)(void *devdata, int rw, daddr_t blk,
707 size_t size, char *buf, size_t *rsize);
708 int (*dv_open)(struct open_file *f, ...);
709 int (*dv_close)(struct open_file *f);
710 int (*dv_ioctl)(struct open_file *f, u_long cmd, void *data);
711 int (*dv_print)(int verbose);
712 void (*dv_cleanup)(void);
713 void (*dv_fmtdev)(struct devdesc *);
714};
715.Ed
716.Bl -tag -width ".Fn dv_strategy"
717.It Fn dv_name
718The device's name.
719.It Fn dv_type
720Type of device.
721The supported types are:
722.Bl -tag -width "DEVT_NONE"
723.It DEVT_NONE
724.It DEVT_DISK
725.It DEVT_NET
726.It DEVT_CD
727.It DEVT_ZFS
728.It DEVT_FD
729.El
730Each type may have its own associated (struct type_devdesc),
731which has the generic (struct devdesc) as its first member.
732.It Fn dv_init
733Driver initialization routine.
734This routine should probe for available units.
735Drivers are responsible for maintaining lists of units for later enumeration.
736No other driver routines may be called before
737.Fn dv_init
738returns.
739.It Fn dv_open
740The driver open routine.
741.It Fn dv_close
742The driver close routine.
743.It Fn dv_ioctl
744The driver ioctl routine.
745.It Fn dv_print
746Prints information about the available devices.
747Information should be presented with
748.Fn pager_output .
749.It Fn dv_cleanup
750Cleans up any memory used by the device before the next stage is run.
751.It Fn dv_fmtdev
752Converts the specified devdesc to the canonical string representation
753for that device.
754.El
690.Sh HISTORY
691The
692.Nm
693library contains contributions from many sources, including:
694.Bl -bullet -compact
695.It
696.Nm libsa
697from

--- 19 unchanged lines hidden --- 		755.Sh HISTORY
756The
757.Nm
758library contains contributions from many sources, including:
759.Bl -bullet -compact
760.It
761.Nm libsa
762from

--- 19 unchanged lines hidden ---