Technical Reference: Communications, Volume 2

sad Device Driver

Purpose

Provides an interface for administrative operations.

Syntax

#include <sys/types.h>
#include <sys/conf.h>
#include <sys/sad.h>
#include <sys/stropts.h>

int ioctl (fildes, command, arg) int fildes, command; int arg;

Description

The STREAMS Administrative Driver (sad) provides an interface for applications to perform administrative operations on STREAMS modules and drivers. The interface is provided through ioctl operations. Privileged operation can access the sad device driver in the /dev/sad/user directory.

Parameters

fildes	Specifies an open file descriptor that refers to the sad device driver.
command	Determines the control function to be performed.
arg	Supplies additional information for the given control function.

Values for the command Parameter

The autopush command allows a user to configure a list of modules to be automatically pushed on a stream when a driver is first opened. The autopush command is controlled by the following commands.

Command Description

Command	Description
SAD_SAP	Allows the person performing administrative duties to configure the information for the given device, which is used by the autopush command. The arg parameter points to a strapush structure containing the following elements: uint sap_cmd; long sap_major; long sap_minor; long sap_lastminor; long sap_npush; uint sap_list[MAXAPUSH] [FMNAMESZ + 1]; The elements are described as follows: `sap_cmd` Indicates the type of configuration being done. Acceptable values are: SAP_ONE Configures one minor device of a driver. SAP_RANGE Configures a range of minor devices of a driver. SAP_ALL Configures all minor devices of a driver. SAP_CLEAR Undoes configuration information for a driver. `sap_major` Specifies the major device number of the device to be configured. `sap_minor` Specifies the minor device number of the device to be configured. `sap_lastminor` Specifies the last minor device number in a range of devices to be configured. This field is used only with the SAP_RANGE value in the `sap_cmd` field. `sap_npush` Indicates the number of modules to be automatically pushed when the device is opened. The value of this field must be less than or equal to MAXAPUSH, which is defined in the sad.h file. It must also be less than or equal to NSTRPUSH, which is defined in the kernel master file. `sap_list` Specifies an array of module names to be pushed in the order in which they appear in the list. When using the SAP_CLEAR value, the user sets only the `sap_major` and `sap_minor` fields. This undoes the configuration information for any of the other values. If a previous entry was configured with the SAP_ALL value, the `sap_minor` field is set to 0. If a previous entry was configured with the SAP_RANGE value, the `sap_minor` field is set to the lowest minor device number in the range configured. On successful completion, the return value from the ioctl operation is 0. Otherwise, the return value is -1.
SAD_GAP	Allows any user to query the sad device driver to get the autopush configuration information for a given device. The arg parameter points to a strapush structure as described under the SAD_SAP value. The user sets the `sap_major` and `sap_minor` fields to the major and minor device numbers, respectively, of the device in question. On return, the strapush structure is filled with the entire information used to configure the device. Unused entries are filled with zeros. On successful completion, the return value from the ioctl operation is 0. Otherwise, the return value is -1.
SAD_VML	Allows any user to validate a list of modules; that is, to see if they are installed on the system. The arg parameter is a pointer to a str_list structure containing the following elements: int sl_nmods; struct str_mlist *sl_modlist; The str_mlist structure contains the following element: char l_name[FMNAMESZ+1]; The fields are defined as follows: `sl_nmods` Indicates the number of entries the user has allocated in the array. `sl_modlist` Points to the array of module names.

SAD_SAP

Allows the person performing administrative duties to configure the information for the given device, which is used by the autopush command. The arg parameter points to a strapush structure containing the following elements:

uint sap_cmd;
long sap_major;
long sap_minor;
long sap_lastminor;
long sap_npush;
uint sap_list[MAXAPUSH] [FMNAMESZ + 1];

The elements are described as follows:

sap_cmd

Indicates the type of configuration being done. Acceptable values are:

SAP_ONE: Configures one minor device of a driver.
SAP_RANGE: Configures a range of minor devices of a driver.
SAP_ALL: Configures all minor devices of a driver.
SAP_CLEAR: Undoes configuration information for a driver.

sap_major

Specifies the major device number of the device to be configured.

sap_minor

Specifies the minor device number of the device to be configured.

sap_lastminor

Specifies the last minor device number in a range of devices to be configured. This field is used only with the SAP_RANGE value in the sap_cmd field.

sap_npush

Indicates the number of modules to be automatically pushed when the device is opened. The value of this field must be less than or equal to MAXAPUSH, which is defined in the sad.h file. It must also be less than or equal to NSTRPUSH, which is defined in the kernel master file.

sap_list

Specifies an array of module names to be pushed in the order in which they appear in the list.

When using the SAP_CLEAR value, the user sets only the sap_major and sap_minor fields. This undoes the configuration information for any of the other values. If a previous entry was configured with the SAP_ALL value, the sap_minor field is set to 0. If a previous entry was configured with the SAP_RANGE value, the sap_minor field is set to the lowest minor device number in the range configured.

On successful completion, the return value from the ioctl operation is 0. Otherwise, the return value is -1.

SAD_GAP

Allows any user to query the sad device driver to get the autopush configuration information for a given device. The arg parameter points to a strapush structure as described under the SAD_SAP value.

The user sets the sap_major and sap_minor fields to the major and minor device numbers, respectively, of the device in question. On return, the strapush structure is filled with the entire information used to configure the device. Unused entries are filled with zeros.

On successful completion, the return value from the ioctl operation is 0. Otherwise, the return value is -1.

SAD_VML

Allows any user to validate a list of modules; that is, to see if they are installed on the system. The arg parameter is a pointer to a str_list structure containing the following elements:

int sl_nmods;
struct str_mlist *sl_modlist;

The str_mlist structure contains the following element:

char l_name[FMNAMESZ+1];

The fields are defined as follows:

sl_nmods: Indicates the number of entries the user has allocated in the array.
sl_modlist: Points to the array of module names.

Return Values

On successful completion, the return value from the ioctl operation is 0 if the list is valid or 1 if the list contains an invalid module name. Otherwise the return value is -1.

Error Codes

On failure, the errno global variable is set to one of the following values:

Value	Description
EFAULT	The arg parameter points outside the allocated address space.
EINVAL	The major device number is not valid, the number of modules is not valid. OR The list of module names is not valid.
ENOSTR	The major device number does not represent a STREAMS driver.
EEXIST	The major-minor device pair is already configured.
ERANGE	The value of the command parameter is SAP_RANGE and the value in the `sap_lastminor` field is not greater than the value in the `sap_minor` field. OR The value of the command parameter is SAP_CLEAR and the value in the `sap_minor` field is not equal to the first minor in the range.
ENODEV	The value in the command parameter is SAP_CLEAR and the device is not configured for the autopush command.
ENOSR	An internal autopush data structure cannot be allocated.

Related Information

The autopush command.

The close subroutine, fstat subroutine, open subroutine, stat subroutine.

Understanding streamio (STREAMS ioctl) Operations, Understanding STREAMS Drivers and Modules, Understanding the log Device Driver in AIX 5L Version 5.2 Communications Programming Concepts.