libIO(3X)libIO(3X)NAME
libIO: io_block_to_char_dsf(), io_block_to_raw(),
io_char_to_block_dsf(), io_dev_to_node(), io_dev_to_options(),
io_end(), io_error, io_get_devs(), io_get_legacy_mode(), io_get_map‐
ping(), io_get_node_relation(), io_hw_compare(), io_hw_compare_ext(),
io_hw_path_to_node(), io_hw_path_to_str(), io_init(),
io_init_hw_path(), io_is_hwpath_legacy(), io_is_legacy_dev(),
io_is_legacy_token(), io_is_option_set(), io_legacy_to_new_dev(),
io_legacy_to_new_dsf(), io_legacy_to_new_hwpath(), io_mkdev(),
io_mkdev_ext(), io_new_to_legacy_devs(), io_new_to_legacy_dsfs(),
io_new_to_legacy_hwpath(), io_node_to_hw_path(), io_query(),
io_query_array(), io_query_batch(), io_raw_to_block(), io_search(),
io_search_array(), io_search_array_batch(), io_str_to_hw_path(),
io_strerror(), - interface for interacting with kernel I/O subsystem
SYNOPSIS
Remarks
Each function in is described in its own section below.
DESCRIPTION
The library provides APIs to access the I/O subsystem through the
driver. This manpage describes each API and the associated data struc‐
tures.
The section under each API lists the possible values that is set when
the API fails. The section at the end of the manpage provides an
explanation of each error value.
To use the library, (for Itanium(R)-based systems) or (for PA-RISC sys‐
tems), the program must link it using
I/O Subsystem Terms
The following are some common I/O subsystem terminologies and struc‐
tures used in this manpage.
A handle used for uniquely identifying an object in I/O subsystem (rep‐
resented by
A kernel data structure representation for a group of I/O nodes.
An extern variable used to store the
specific error number when a API fails. The usage is similar to
(see errno(2)).
See mknod(5).
A data structure for storing hardware paths used for releases
prior to HP-UX 11i V3. This structure has only 14 elements of
type
A data structure for storing hardware paths used for HP-UX 11i V3
and later releases. This structure can have up to 64 elements
of type
LibIO APIs
Here are the APIs provided for HP-UX 11i V3.
Maps a block device special file to character device special file
Returns the character
of the given block
Maps a character device special file to block device special file
Converts a
to token
Returns the device options of a given
and dev_type
Terminates a connection with the
driver
Provides
error messages
Returns the
of a given node
Returns the state of legacy mode
Returns a mapping between a given node and other I/O nodes
Retrieve a relative of a given node token
Compares two pre-HP-UX 11i V3 hardware path structures
Compares two hardware path structures used on HP-UX 11i V3 or later
Converts a hardware path to token
Converts a hardware path to a string
Establishes a connection with the
driver
Initializes the hardware path with the passed flags argument
Determines if the given hardware path is of legacy or agile form
Determines if the given
is legacy
Determines if token is legacy or agile
Determines if the option(s) is set for
Maps a legacy
to an agile
Maps a legacy device special file to a persistent device special file
Converts the data structure of a pre-HP-UX 11i V3 hardware path
to that of the hardware path for HP-UX 11i V3 or later.
Builds a
given a node and option string
Returns a
for the given node, dev_type, and device options
Maps an agile
to one or more legacy
Maps a agile device special file to one or more legacy device special
file
Converts the data structure of a hardware path used on HP-UX 11i V3 or
later
to that of a pre-HP-UX 11i V3 hardware path.
Converts token to a hardware path
Gets information about a token
Gets information (multiple fields) about a token
Creates multiple keys to call
Returns the block
of the given character
Searches I/O subsystem data structures
Searches I/O system data structures
Retrieves an array of token matching the search
Converts a string representing the hardware path to
structure
Provides
error messages
These APIs are described in more detail in the following sections.
libIO FUNCTION
Name
- establishes/terminates a connection with the driver
Synopsis
Description
The library uses the driver to access information in the kernel I/O
data structures.
Opens the device special file, which causes an open(2) of the
driver.
must be called before calling any other routine in the
library.
Causes a close(2) of the driver.
must be called after the use of the library routine(s).
Note that each call should be paired with a call to
Arguments
flag Specifies a flag to be passed to open(2) of the device
special file.
Defined values are:
Open for read accesses only.
Open for write accesses only.
Open for read and write accesses.
Example
... User code ...
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
has no return value.
Errors
libIO FUNCTION
Name
- error messages
Synopsis
Description
writes an error message to standard error describing the last error
encountered during a call to API. The argument str would normally
include the name of the program/function that called the API and
incurred the error. The external variable io_errno contains the error
value of the last error (if any) caused by a API. The value of this
variable should be checked right after the API failure and it is not
reset by any other API.
See the section below for an explanation of each error value.
The printed message has the form:
If str is NULL, the message has the form:
returns a pointer to the string containing the error message which maps
to the passed argument errnum.
Arguments
str Caller specified string to print along with error sta‐
tus
errnum Caller specified error number to map to error message
string
Return Value
Pointer to the message string - Upon success.
NULL - Otherwise.
has no return value.
Errors
None.
libIO FUNCTION
Name
- converts a to token
Synopsis
Description
returns a token corresponding to the specified dev_type. See mknod(5).
Arguments
dev to map to node.
dev_type Possible values are:
Character
Block
Return Value
Token - Upon success.
NULL - Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- compares two pre-HP-UX 11i V3 hardware path structures
Synopsis
Description
compares contents of two structures. If found equivalent, returns suc‐
cess; otherwise, returns an error. is a pre-HP-UX 11i V3 structure
used for storing hardware paths.
Arguments
path1, path2 Pointers to structures.
Return Value
- If found equivalent.
- Not equivalent.
Errors
None.
libIO FUNCTION
Name
- compares two hardware path structures used on HP-UX 11i V3 or later
Synopsis
Description
compares contents of two structures. If found equivalent, returns suc‐
cess; otherwise, returns an error. is a hardware path structure used
on HP-UX 11i V3 or later.
Arguments
path1, path2 Pointers to structures.
Return Value
- If found equivalent.
- Not equivalent.
Errors
libIO FUNCTION
Name
- converts a hardware path to token
Synopsis
Description
returns the token for the specified hardware path.
Arguments
hw_path Pointer to hardware path.
Return Value
Token - Upon success.
NULL - Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- converts a hardware path to a string
Synopsis
Description
converts the hardware path specified by hw_path to the string pointed
to by str. str must have enough space (maximum hardware path length -
to hold the converted string. If str is NULL, then no data is trans‐
ferred, and the length of the string is returned instead.
Arguments
str Pointer to string representing hardware path.
hw_path Input hardware path structure.
Example
The following prints the hardware path of the I/O tree node represented
by
Return Value
Number of bytes in the string - Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- converts a string representing the hardware path to structure
Synopsis
Description
fills hw_path with the hardware path, given a string representing the
passed path parameter.
Arguments
str Pointer to string representing hardware path.
hw_path Hardware path.
Example
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- determines if the option(s) is set for
Synopsis
Description
calls with and without options to generate option mask. Mask is then
bitwise "ANDed" with dev argument and the boolean result is returned.
This routine does not distinguish between one or more options set or
multi-bit options.
Arguments
dev to check for option settings.
dev_type Possible values are:
Character
Block
options NULL terminated string indicating device specific
options.
Return Value
- If one or more of specified options set.
- Otherwise.
Errors
None.
libIO FUNCTION
Name
- builds a given a node and option string
Synopsis
Description
builds a pointed to by dev from the given node and options.
Arguments
node Token corresponding to an I/O tree node.
dev_type Possible values are:
Character
Block
dev Pointer to
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- converts token to a hardware path
Synopsis
Description
fills hw_path with the hardware path of the given node.
Arguments
node Token corresponding to I/O node.
hw_path Hardware path of node.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- gets information about a token
Synopsis
Description
is used to get information about a token previously obtained by a call
to The data corresponding to key is copied to the buffer pointed to by
ptr. key must be one of the strings known to the I/O subsystem. Note
that not all keys are defined for all queries. If ptr is NULL, then
just returns the number of bytes which would have been copied. See the
examples in
It is the users responsibility to ensure that the buffer pointed to by
ptr is large enough to contain the requested information.
Arguments
token Token returned by a call to
type Specifies type of query.
Only one should be specified. The defined values
are:
Causes a query of the I/O tree.
Causes a query of the agile I/O tree.
Causes a query of a block device switch table.
Causes a query of a character device switch table.
key String corresponding to query field.
ptr Pointer to copy of queried data.
Return Value
Number of bytes copied - Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- creates multiple keys to call
Synopsis
Description
This routine copies the key/dat arguments (one or more pair) into an
array and calls with the passed search parameters.
Arguments
token Token returned by previous call to
type Specifies type (see
key Query field string.
dat Query field data.
Return Value
See section of
Errors
See the section of
libIO FUNCTION
Name
- gets information (multiple fields) about a token
Synopsis
Description
This routine is an enhancement to It returns multiple fields for a
token at one time.
Arguments
token Token returned by previous call to
type Type of query (see
nkeys Number of keys in the query.
key[ ] An array of query field string.
ptr[ ] An array of corresponding query field data.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- searches I/O subsystem and system data structures
Synopsis
Description
This function is used to search for I/O system information. The token
returned corresponds to an entry in the I/O tree or one of the other
tables which can be specified in type. The token can be used with the
command to obtain information about the token.
Arguments
token Token returned by a previous call to or NULL if first
search.
type Specifies type of search (see
qual Qualifiers for search. More than one may be specified by
bitwise "ORing" values into qual. Defined values are:
Software is associated with the I/O tree node.
Hardware is associated with I/O tree node.
Is a pseudo device driver.
Has switch table entry points.
On I/O tree searches, return entire subtree under match‐
ing node.
Newly found hardware.
Allows transparent nodes to be returned.
Matches console device.
Matches dump devices.
Matches boot device.
Matches root filesystem devices.
Matches swap devices.
I/O tree node information saved in ioconfig files.
(See
key A string corresponding to a defined query field. For
this is a NULL terminated array of strings.
is the maximum array size.
dat A pointer to data to match for query field indicated in
key. There must be a dat given for every listed key. is
the maximum data size.
Return Value
- Upon success.
NULL - Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- retrieves an array of token matching the search
Synopsis
Description
This routine is an enhancement of it returns an array of tokens.
Arguments
token Token returned by previous call to or NULL if first
search.
type Specifies type of search (see
qual Qualifier for search (see
key[] An array of query field string.
dat[] An array of corresponding query field data.
ret_roken[]
An array of token returned.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- returns a for the given node, dev_type, and device options
Synopsis
Description
builds a from the given node, device type and options. This API is for
creating a for an agile node only. is set to if called on legacy
nodes.
Arguments
node Token corresponding to the I/O node.
dev_type Possible values are:
Character
Block
options Device specific options.
dev The created is stored in memory pointed to by dev.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- returns the device options of a given and dev_type
Synopsis
Description
Given and dev_type, returns its device options in a bit mask format.
Arguments
dev value to retrieve the device options.
dev_type Possible values are:
Character
Block
options Unsigned 64-bit mask representing the device options
is stored in the location pointed to by options.
Return Value
- Upon success.
- Failure. is set to indicate the error.
Errors
libIO FUNCTION
Name
- determines if the given is legacy
Synopsis
Description
This API determines if the given is a legacy or an agile While checking
if a given device special file is persistent or legacy, issue a call on
the device special file and pass (see stat(2)) to this API. The device
special file is of persistent type if the API returns and the file is
of legacy type if the API returns
Arguments
dev of the I/O node.
dev_type Possible values are:
Character
Block
Return Value
- If is of an agile I/O node.
- If is of a legacy I/O node.
- Failure. is set to indicate the error.
Errors
libIO FUNCTION
Name
- determines if token is legacy or agile
Synopsis
Description
This API accepts a token and determines whether it is of type agile or
legacy form.
Arguments
token I/O node token.
Return Value
- If is of an agile node.
- If is of a legacy node.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- returns the state of legacy mode
Synopsis
Description
This API is called to retrieve the state of legacy mode. The value
returned in the argument mode will specify if the legacy mode is cur‐
rently enabled or disabled (see rmsf(1M) and insf(1M)).
Arguments
mode A pointer to an unsigned integer.
1 Value set if legacy mode is enabled.
0 Value set if the legacy mode is disabled.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- returns a mapping between a given node and other I/O nodes
Synopsis
Description
This API is called to retrieve the node or nodes mapped to a given node
token.
Given a legacy token with a map_type of the routine will return an
agile token mapped to it.
Given an agile token with a map_type of the routine will return one or
more legacy token(s).
Given a LUN token with a map_type of the routine will return one or
more lunpath token(s) mapped to it.
Likewise, if given a lunpath token and a map_type of a LUN token will
be returned.
Arguments
node A node token to which mappings will be returned.
map_type Possible values are:
Obtains the agile node token from the given legacy
token.
This is a one to one mapping.
Obtains the legacy node token from the given agile
node token. This can be a one to many map‐
ping.
Obtains the lunpath token from the given lun node
token. This can be a one to many mapping.
Obtains the lun node token from the given lunpath
token. This mapping is a one to one mapping.
token_arry Possible values are:
A pointer to an array of
Recommended size is:
The io_token_t(s) returned will be copied into
this array.
count The values are:
Number of tokens to be returned in the
token_array.
10 is the recommended for the initial count.
Number of actual
io_token_t(s) in the returned token_array.
If the array is not big enough:
1) No token will be returned,
2) Count will be set to the real count of
io_token_t to be returned,
3) The API will return
4) will be set to
In this case, the caller needs to allo‐
cate a bigger buffer after recalculating
it using:
with the returned count value. and needs
to call the API again with the new buffer
and count values.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- determines if the given hardware path is of legacy or agile form
Synopsis
Description
This API accepts a hardware path in string format and determines
whether it is a legacy path or agile hardware path.
Arguments
path A pointer to a string representing a hardware path.
Return Value
- If the path is an agile path.
- If the path is a legacy path.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- retrieves a relative of a given node token
Synopsis
Description
This API is called to get the relative of the I/O node specified by
node. The parameter relationship indicates what kind of relative.
Valid values are:
·
·
·
The node token of the relative is returned in the parameter relative.
If either or is specified, then the parameters addr and relative can be
used to specify which child or sibling.
If the parameter relative is NULL, then addr is used to identify a par‐
ticular child or sibling.
If the parameter relative is not NULL, then the parameter addr is
ignored, and if relative == node, the first child or sibling is
returned, otherwise the next child or sibling after the one identified
by relative is returned.
Arguments
node The token of the I/O node.
relationship What relative to look for:
Look for a child node.
Look for the parent node.
Look for a sibling.
addr The (optional) address of the relative if child
or sibling relative to the parent.
relative Either NULL or the handle of the last relative
found.
Note that NULL means the relative pointer is
pointing to a NULL. It does not mean a NULL
pointer.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- converts the data structure of a pre-HP-UX 11i V3 hardware path to
that of the hardware path for HP-UX 11i V3 or later
Synopsis
Description
converts a pre-HP-UX 11i V3 hardware path data structure to the hard‐
ware path for HP-UX 11i V3 or later
Arguments
from Pointer to a data structure.
to A pointer to the data structure.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- converts the data structure of a hardware path used on HP-UX 11i V3
or later to that of a pre-HP-UX 11i V3 hardware path
Synopsis
Description
converts a hardware path used on HP-UX 11i V3 or later data structure
to the pre-HP-UX 11i V3 hardware path If has more than 14 elements or
any of them is more than 8 bit long, the API will set to
Arguments
from Pointer to data structure.
to A pointer to the legacy data structure.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- returns the of a given node
Synopsis
Description
gets all the (including char and block of a given node. It will return
all the the device specific options and the type in dev_arry. The
dev_type field of dev_arry is updated to say if the type is (character)
or (block).
The user will need to allocate memory for the array and indicate its
size (of io_dev_info_t) in count. The interface will copy the data
into the array if it is big enough. If it is too small, no data is
returned and the count is set to indicate the needed size (number of
io_dev_info_t). Callers need to reallocate and call the API again.
Arguments
node An I/O node token to retrieve its
dev_arry Possible values are:
A pointer to an array of
io_dev_info_t. The array is allocated by the
caller. The initial size can be (this is cur‐
rently set to 48).
The returned will be copied into this array.
count Possible values are:
Number of
io_dev_info_t expected. Should be set to ini‐
tially.
Number of
io_dev_info_t in the returned array if the
array is big enough. If the array is not big
enough:
1) No token will be returned.
2) Count will be set to the real count of
io_dev_info_t to be returned.
3) The API will return
4) will be set to
In this case, the caller needs to allocate
a bigger buffer after recalculating it
using:
with the returned count value. and needs to
call the API again with the new buffer and
count values.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- returns the character of the given block
Synopsis
Description
This API is used to retrieve character corresponding to the block
Arguments
bdev Block whose character is needed.
rdev The retrieved character of the given block is stored
here through the pointer.
in case of an error.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- maps a block device special file to character device special file
Synopsis
Description
This API maps a given block device special file to its corresponding
character device special file.
Arguments
block_dsf Pointer to a block device special file to be mapped
to a character device special file.
char_dsf A pointer to a buffer with size
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- map a char device special file to block device special file
Synopsis
Description
This API maps a given character device special file to its correspond‐
ing block device special file.
Arguments
char_dsf A pointer to a character device special file to be
mapped to a block device special file.
block_dsf A pointer to a buffer with size
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- returns the block of the given character
Synopsis
Description
This API is used to retrieve block corresponding to the character
Arguments
rdev Character whose block is needed.
bdev The retrieved block of the given character is stored
here through the pointer. in case of an error.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- maps a legacy to an agile
Synopsis
Description
Given a legacy and dev_type, this API retrieves its agile
Arguments
legacy_dev Legacy to retrieve the agile
dev_type Possible values are:
Character
Block
new_dev The agile is stored here.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- maps a legacy device special file to a persistent device special file
Synopsis
Description
This API converts a given legacy device special file to persistent
device special file.
Arguments
legacy_dsf Legacy device special file to find its corre‐
sponding persistent device special file.
new_dsf A pointer to a buffer of length
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- maps an agile to one or more legacy
Synopsis
Description
This API maps an agile to its legacy There can be one to many mappings.
Arguments
new_dev A pointer to the agile to obtain its corresponding
legacy
dev_type Possible values are:
Character
Block
dev_arry Possible values are:
A pointer to an array of legacy
The array is allocated by the caller with a
recommended initial size of:
The returned will be copied into this array.
count Possible values are:
Number of legacy
expected (recommended (48)).
Number of legacy
in the returned array. If the array is not
big enough:
1) No token will be returned.
2) Count will be set to the real count of to
be returned.
3) The API will return
4) will be set to
In this case, the caller needs to allo‐
cate a bigger buffer after recalculating
it using:
with the returned count value. and needs
to call the API again with the new buffer
and count values.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- maps a agile device special file to one or more legacy device special
file
Synopsis
Description
This API retrieves legacy device special file(s) corresponding to a
persistent device special file. There can be one to many mappings.
Arguments
new_dsf A pointer to a persistent device special file to
retrieve its legacy device special files.
legacy_arry Possible values are:
A pointer to a buffer to store the returned
legacy device special files.
The buffer is allocated by the caller. By
default the size of the buffer should be
and the count should be set to 10.
The device special files returned will be copied
into this array.
Each device special file is delimited by a
semi-colon
count Possible values are:
Number of legacy device special files expected.
Initial size should be 10.
Number of legacy device special files in the
returned array if the
array is big enough. If the array is not
big enough:
1) No token will be returned.
2) Count will be set to the real count of
device special files to be returned.
3) The API will return
4) will be set to
In this case, the caller needs to
allocate a bigger buffer after recal‐
culating it
with the returned count value. and
needs to call the API again with the
new buffer and count values.
Return Value
- Upon success.
- Otherwise. is set to indicate the error.
Errors
libIO FUNCTION
Name
- initializes the hardware path with the passed flags argument
Synopsis
Description
This API initializes the hardware path structure according to the spec‐
ified flags argument. should be passed as flags value when initializ‐
ing a legacy hardware path. See intro(7). Zero can be passed as flags
value for all other cases.
Arguments
hw_path Pointer to hardware path structure.
flags The flags field of the hardware path.
The valid flags are 0 and
Return Value
- Upon success.
- Otherwise.
Errors
None.
LIBIO_ERRORS
The following describes the values, which are set after a API failure.
User buffer too small.
permission denied.
does not exist.
is not open.
Dynamic major not defined for specified node.
Functionality not supported.
Key is undefined for specified token, or token is NULL.
No match found.
Unable to allocate memory.
Another IO event is in progress.
Not able to destroy specified node or a descendent of node.
I/O tree node does not exist.
Node already exists or parameter error detected.
Operation failed.
Invalid open flag.
Parameter error.
String does not represent a valid path.
System call error.
Unexpected error.
The call would block in the kernel.
MULTITHREAD USAGE
The APIs are not thread-safe.
WARNINGS
Many APIs in are release specific. These APIs may be removed or have
its meaning changed in future releases of HP-UX.
AUTHOR
was developed by HP.
FILES
data structures and identifiers.
32 bit for PA-RISC systems.
64 bit for PA-RISC systems.
32 bit for Itanium-based systems.
64 bit for Itanium-based systems.
SEE ALSO
insf(1M), ioscan(1M), rmsf(1M), ioconfig(4), intro(7).
libIO(3X)
