[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Technical Reference: Communications, 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.
This utility is part of STREAMS Kernel Extensions.
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:
Element |
Description |
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:
Code |
Description |
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. |
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.2 Communications Programming Concepts.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]