Technical Reference: Communications, Volume 2

str_install Utility

Syntax

#include <sys/strconf.h>

int str_install(cmd, conf) int cmd; strconf_t * conf;

The str_install utility adds or removes Portable Streams Environment (PSE) drivers and modules from the internal tables of PSE. The extension is pinned when added and unpinned when removed (see the pincode kernel service). It uses a configuration structure to provide sufficient information to perform the specified command.

The configuration structure, strconf_t, is defined as follows:

typedef struct {
        char *sc_name;
        struct streamtab *sc_str;
        int sc_open_stylesc_flags;
        int sc_major;
        int sc_sqlevel;
        caddr_t sc_sqinfo;
} strconf_t;

The elements of the strconf_t structure are defined as follows:

`sc_name`	Specifies the name of the extension in the internal tables of PSE. For modules, this name is installed in the fmodsw table and is used for I_PUSH operations. For drivers, this name is used only for reporting with the scls and strinfo commands.
`sc_str`	Points to a streamtab structure.
`sc_open_stylesc_flags`	Specifies the style of the driver or module open routine. The acceptable values are: STR_NEW_OPEN Specifies the open syntax and semantics used in System V Release 4. STR_OLD_OPEN Specifies the open syntax and semantics used in System V Release 3. If the module is multiprocessor-safe, the following flag should be added by using the bitwise OR operator: STR_MPSAFE Specifies that the extension was designed to run on a multiprocessor system. If the module uses callback functions that need to be protected against interrupts (non-interrupt-safe callback functions) for the timeout or bufcall utilities, the following flag should be added by using the bitwise OR operator: STR_QSAFETY Specifies that the extension uses non-interrupt-safe callback functions for the timeout or bufcall utilities. This flag is automatically set by STREAMS if the module is not multiprocessor-safe. STR_PERSTREAM Specifies that the module accepts to run at perstream synchronization level. STR_Q_NOTTOSPEC Specifies that the extension is designed to run it's service routine under process context. By default STREAMS service routine runs under interrupt context (INTOFFL3). If Streams drivers or modules want to execute their service routine under process context (INTBASE), they need to set this flag. STR_64BIT Specifies that the extension is capable to support 64-bit data types. STR_NEWCLONING Specifies the driver open uses new-style cloning. Under this style, the driver open() is not checking for CLONEOPEN flag and returns new device number.
`sc_major`	Specifies the major number of the device.
`sc_sqlevel`	Reserved for future use. Specifies the synchronization level to be used by PSE. There are seven levels of synchronization: SQLVL_NOP No synchronization Specifies that each queue can be accessed by more than one thread at the same time. The protection of internal data and of put and service routines against the timeout or bufcall utilities is done by the module or driver itself. This synchronization level should be used essentially for multiprocessor-efficient modules. SQLVL_QUEUE Queue Level Specifies that each queue can be accessed by only one thread at the same time. This is the finest synchronization level, and should only be used when the two sides of a queue pair do not share common data. SQLVL_QUEUEPAIR Queue Pair Level Specifies that each queue pair can be accessed by only one thread at the same time. SQLVL_MODULE Module Level Specifies that all instances of a module can be accessed by only one thread at the same time. This is the default value. SQLVL_ELSEWHERE Arbitrary Level Specifies that a group of modules can be accessed by only one thread at the same time. Usually, the group of modules is a set of cooperating modules, such as a protocol family. The group is defined by using the same name in the `sc_sqinfo` field for each module in the group. SQLVL_GLOBAL Global Level Specifies that all of PSE can be accessed by only one thread at the same time. This option should normally be used only for debugging. SQLVL_DEFAULT Default Level Specifies the default level, set to SQLVL_MODULE.
`sc_sqinfo`	Specifies an optional group name. This field is only used when the SQLVL_ELSEWHERE arbitrary synchronization level is set; all modules having the same name belong to one group. The name size is limited to eight characters.

Parameters

cmd

Specifies which operation to perform. Acceptable values are:

STR_LOAD_DEV: Adds a device into PSE internal tables.
STR_UNLOAD_DEV: Removes a device from PSE internal tables.
STR_LOAD_MOD: Adds a module into PSE internal tables.
STR_UNLOAD_MOD: Removes a module from PSE internal tables.

conf

Points to a strconf_t structure, which contains all the necessary information to successfully load and unload a PSE kernel extension.

Return Values

On successful completion, the str_install utility returns a value of 0. Otherwise, it returns an error code.

Error Codes

On failure, the str_install utility returns one of the following error codes:

EBUSY	The PSE kernel extension is already in use and cannot be unloaded.
EEXIST	The PSE kernel extension already exists in the system.
EINVAL	A parameter contains an unacceptable value.
ENODEV	The PSE kernel extension could not be loaded.
ENOENT	The PSE kernel is not present and could not be unloaded.
ENOMEM	Not enough memory for the extension could be allocated and pinned.
ENXIO	PSE is currently locked for use.

Implementation Specifics

This utility is part of STREAMS Kernel Extensions.

Related Information

The pincode kernel service, unpincode kernel service.

The streamio operations.

Configuring Drivers and Modules in the Portable Streams Environment (PSE) and List of Streams Programming References in AIX 5L Version 5.1 Communications Programming Concepts.