str_install Utility

AIX Version 4.3 Communications Technical Reference, Volume 2

str_install Utility

Purpose

Installs streams modules and drivers.

Syntax

#include <sys/strconf.h>

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

Description

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 Version 4.3 Communications Programming Concepts.