'\"macro stdmacro
.if n .pH g7.sad @(#)sad	40.7 of 11/7/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} sad 7 "" "\&"
.if \nX=1 .ds x} sad 7 ""
.if \nX=2 .ds x} sad 7 "" "\&"
.if \nX=3 .ds x} sad "" "" "\&"
.TH \*(x}
.SH NAME
sad - \s-1STREAMS\s+1 Administrative Driver
.SH SYNOPSIS
.nf
\f4#include <sys/types.h>
#include <sys/conf.h>
#include <sys/sad.h>
#include <sys/stropts.h>
.sp
int ioctl (fildes, command, arg);
int fildes, command;\f1
.fi
.SH DESCRIPTION
.P
The \s-1STREAMS\s+1 Administrative Driver provides an interface for 
applications to perform administrative operations on \s-1STREAMS\s+1 modules and 
drivers.
The interface is provided through \f4ioctl\fP(2) commands.
Privileged operations may access the \f4sad\fP driver via \f4/dev/sad/admin\fP. 
Unprivileged operations may access the \f4sad\fP driver via \f4/dev/sad/user\fP.
.P
\f2fildes\f1 is an open file descriptor that refers to the \f4sad\fP driver.
\f2command\f1 determines the control function to be performed as described below.
\f2arg\f1 represents additional information that is needed by this command.
The type of \f2arg\f1 depends upon the command, but it is generally an integer
or a pointer to a \f2command\f1-specific data structure.
.SH COMMAND FUNCTIONS
The autopush facility [see \f4autopush\f1(1M)] allows one to configure
a list of modules to be automatically pushed on a stream when a driver is 
first opened.
Autopush is controlled by the next commands.
.TP 13
\f4SAD_SAP\fP
Allows the administrator to configure the autopush information for the given
device.
\f2arg\f1 points to a \f4strapush\f1 structure which contains the following
members:
.sp .5
.ta .5i 1.75i
.nf
	\f4uint   sap_cmd;
	long   sap_major;
	long   sap_minor;
	long   sap_lastminor;
	long   sap_npush;
	uint   sap_list[MAXAPUSH] [FMNAMESZ + 1];\f1
.fi
.sp .5
The \f4sap_cmd\f1 field indicates the type of configuration being done.
It may take on one of the following values:
.RS 13
.TP 13
\f4SAP_ONE\fP
Configure one minor device of a driver.
.TP
\f4SAP_RANGE\fP
Configure a range of minor devices of a driver.
.TP
\f4SAP_ALL\fP
Configure all minor devices of a driver.
.TP
\f4SAP_CLEAR\fP
Undo configuration information for a driver.
.P
The \f4sap_major\f1 field is the major device number of the device to be configured.
The \f4sap_minor\f1 field is the minor device number of the device to be configured.
The \f4sap_lastminor\f1 field is used only with the \f4SAP_RANGE\fP command, with
which a range of minor devices between \f4sap_minor\f1 and \f4sap_lastminor\f1,
inclusive, are to be configured.
The minor fields have no meaning for the \f4SAP_ALL\fP command.
The \f4sap_npush\f1 field indicates the number of modules to be automatically
pushed when the device is opened.
It must be less than or equal to \f4MAXAPUSH\fP, defined in \f4sad.h\f1.
It must also be less than or equal to \f4NSTRPUSH\fP, the maximum number of 
modules that can be pushed on a stream, defined in the kernel master file.
The field \f4sap_list\f1 is an array of module names to be pushed in the order 
in which they appear in the list.
.P
When using the \f4SAP_CLEAR\fP command, the user sets only \f4sap_major\f1 and
\f4sap_minor\f1.
This will undo the configuration information for any of the other commands.
If a previous entry was configured as \f4SAP_ALL, sap_minor\f1 should 
be set to zero.
If a previous entry was configured as \f4SAP_RANGE, sap_minor\f1 should
be set to the lowest minor device number in the range configured.
.P
On failure, \f4errno\f1 is set to the following value:
.RE
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.TP 13
\f4EINVAL\fP
The major device number is invalid, the number of modules is invalid, or the
list of module names is invalid.
.TP 13
\f4ENOSTR\fP
The major device number does not represent a \s-1STREAMS\s+1 driver.
.TP 13
\f4EEXIST\fP
The major-minor device pair is already configured.
.TP 13
\f4ERANGE\fP
The command is \f4SAP_RANGE\fP and \f4sap_lastminor\fP is not greater than 
\f4sap_minor\fP, or the command is \f4SAP_CLEAR\fP and \f4sap_minor\fP is not
equal to the first minor in the range.
.TP 13
\f4ENODEV\fP
The command is \f4SAP_CLEAR\fP and the device is not configured for autopush.
.TP 13
\f4ENOSR\fP
An internal autopush data structure cannot be allocated.
.RE
.TP 13
\f4SAD_GAP\fP
Allows any user to query the \f4sad\fP driver to get the autopush 
configuration information for a given device.
\f2arg\f1 points to a \f4strapush\f1 structure as described in the previous
command.
.IP
The user should set the \f4sap_major\f1 and \f4sap_minor\f1 fields of the
\f4strapush\f1 structure to the major and minor device numbers, respectively, of
the device in question.
On return, the \f4strapush\f1 structure will be filled in with the entire
information used to configure the device.
Unused entries in the module list will be zero-filled.
.IP
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.TP 13
\f4EINVAL\fP
The major device number is invalid.
.TP 13
\f4ENOSTR\fP
The major device number does not represent a \s-1STREAMS\s+1 driver.
.TP 13
\f4ENODEV\fP
The device is not configured for autopush.
.RE
.TP 13
\f4SAD_VML\fP
Allows any user to validate a list of modules (i.e., to see if they are installed 
on the system.)
\f2arg\fP is a pointer to a \f4str_list\fP structure with the following members:
.sp .5
.ta .5i 1.75i
.nf
	\f4int	sl_nmods;
	struct str_mlist	*sl_modlist;\f1
.fi
.sp .5
The \f4str_mlist\f1 structure has the following member:
.sp .5
.ta .5i 1.75i
.nf
	\f4char	l_name[FMNAMESZ+1];\f1
.fi
.sp .5
\f4sl_nmods\f1 indicates the number of entries the user has allocated in the array
and \f4sl_modlist\f1 points to the array of module names.
The return value is 0 if the list is valid, 1 if the list contains an invalid module
name, or \-1 on failure.
On failure, \f4errno\f1 is set to one of the following values:
.RS 13
.TP 13
\f4EFAULT\fP
\f2arg\f1 points outside the allocated address space.
.TP 13
\f4EINVAL\fP
The \f4sl_nmods\f1 field of the \f4str_list\f1 structure is less than or equal
to zero.
.RE
.SH "SEE ALSO"
\f4intro\fP(2), \f4ioctl\fP(2), \f4open\fP(2).
.br
\f2Programmer's Guide: \s-1STREAMS\s0\f1.
.SH DIAGNOSTICS
Unless specified otherwise above, the return value from \f4ioctl\f1 is 0
upon success and -1 upon failure with \f4errno\f1 set as indicated.
.Ee
