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_mapping(), 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

#include <sys/libIO.h>

Remarks

Each function in NAME is described in its own libIO FUNCTION section below.

DESCRIPTION

The libIO library provides APIs to access the I/O subsystem through the dev_config driver. This manpage describes each libIO API and the associated data structures.

The Errors section under each API lists the possible io_errno values that is set when the API fails. The LIBIO_ERRORS section at the end of the manpage provides an explanation of each error value.

To use the libIO library, libIO.so (for Itanium(R)-based systems) or libIO.sl (for PA-RISC systems), the program must link it using -lIO.

I/O Subsystem Terms

The following are some common I/O subsystem terminologies and structures used in this manpage.

I/O node or token: A handle used for uniquely identifying an object in I/O subsystem (represented by io_token_t).
I/O tree: A kernel data structure representation for a group of I/O nodes.
io_errno: An extern variable used to store the libIO specific error number when a libIO API fails. The usage is similar to errno (see errno(2)).
dev_t: See mknod(5).
leg_hw_path_t: A data structure for storing hardware paths used for releases prior to HP-UX 11i V3. This structure has only 14 elements of type unsigned char.
hw_path_t: 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 hw_addr_t.

LibIO APIs

Here are the libIO APIs provided for HP-UX 11i V3.

io_block_to_char_dsf(): Maps a block device special file to character device special file
io_block_to_raw(): Returns the character dev_t of the given block dev_t
io_char_to_block_dsf(): Maps a character device special file to block device special file
io_dev_to_node(): Converts a dev_t to token
io_dev_to_options(): Returns the device options of a given dev_t and dev_type
io_end(): Terminates a connection with the dev_config driver
io_error(): Provides libIO error messages
io_get_devs(): Returns the dev_ts of a given node
io_get_legacy_mode(): Returns the state of legacy mode
io_get_mapping(): Returns a mapping between a given node and other I/O nodes
io_get_node_relation(): Retrieve a relative of a given node token
io_hw_compare(): Compares two pre-HP-UX 11i V3 hardware path structures
io_hw_compare_ext(): Compares two hardware path structures used on HP-UX 11i V3 or later
io_hw_path_to_node(): Converts a hardware path to token
io_hw_path_to_str(): Converts a hardware path to a string
io_init(): Establishes a connection with the dev_config driver
io_init_hw_path(): Initializes the hardware path with the passed flags argument
io_is_hwpath_legacy(): Determines if the given hardware path is of legacy or agile form
io_is_legacy_dev(): Determines if the given dev_t is legacy
io_is_legacy_token(): Determines if token is legacy or agile
io_is_option_set(): Determines if the option(s) is set for dev_t
io_legacy_to_new_dev(): Maps a legacy dev_t to an agile dev_t
io_legacy_to_new_dsf(): Maps a legacy device special file to a persistent device special file
io_legacy_to_new_hwpath(): 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.
io_mkdev(): Builds a dev_t, given a node and option string
io_mkdev_ext(): Returns a dev_t for the given node, dev_type, and device options
io_new_to_legacy_devs(): Maps an agile dev_t to one or more legacy dev_t(s)
io_new_to_legacy_dsfs(): Maps a agile device special file to one or more legacy device special file
io_new_to_legacy_hwpath(): 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.
io_node_to_hw_path(): Converts token to a hardware path
io_query(): Gets information about a token
io_query_array(): Gets information (multiple fields) about a token
io_query_batch(): Creates multiple keys to call io_query_array()
io_raw_to_block(): Returns the block dev_t of the given character dev_t
io_search(): Searches I/O subsystem data structures
io_search_array(): Searches I/O system data structures
io_search_array_batch(): Retrieves an array of token matching the search
io_str_to_hw_path(): Converts a string representing the hardware path to hw_path_t structure
io_strerror(): Provides libIO error messages

These APIs are described in more detail in the following sections.

libIO FUNCTION

Name

io_init(), io_end() - establishes/terminates a connection with the dev_config driver

Synopsis

int io_init(int flag);

void io_end();

Description

The libIO library uses the dev_config driver to access information in the kernel I/O data structures.

io_init()

Opens the /dev/config device special file, which causes an open(2) of the dev_config driver.

io_init() must be called before calling any other routine in the libIO library.

io_end()

Causes a close(2) of the dev_config driver.

io_end() must be called after the use of the libIO library routine(s).

Note that each io_init() call should be paired with a call to io_end().

Arguments

flag

Specifies a flag to be passed to open(2) of the /dev/config device special file.

Defined values are:

O_RDONLY: Open for read accesses only.
O_WRONLY: Open for write accesses only.
O_RDWR: Open for read and write accesses.

Example

if (io_init(O_RDWR) == -1) exit(1);

... User code ...

io_end();

exit(0);

Return Value

io_init():

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

io_end() has no return value.

Errors

IO_E_DCONF_NOEXIST

IO_E_OPEN_FLAG

IO_E_SYSCALL

libIO FUNCTION

Name

io_error(), io_strerror(), io_errno - libIO error messages

Synopsis

void io_error(char *str);

char *io_strerror(int errnum);

extern int io_errno;

Description

io_error() writes an error message to standard error (stderr) describing the last error encountered during a call to libIO API. The argument str would normally include the name of the program/function that called the libIO API and incurred the error. The external variable io_errno contains the error value of the last error (if any) caused by a libIO API. The value of this variable should be checked right after the API failure and it is not reset by any other libIO API.

See the LIBIO_ERRORS section below for an explanation of each error value.

The printed message has the form:

str:libIO error message <cr>

If str is NULL, the message has the form:

libIO error message <cr>

io_strerror() returns a pointer to the string containing the libIO error message which maps to the passed argument errnum.

Arguments

str: Caller specified string to print along with error status
errnum: Caller specified error number to map to error message string

Return Value

io_strerror():

Pointer to the message string - Upon success.
NULL - Otherwise.

io_error() has no return value.

Errors

None.

libIO FUNCTION

Name

io_dev_to_node() - converts a dev_t to token

Synopsis

#include <sys/types.h>

io_token_t io_dev_to_node(dev_t dev,int dev_type);

Description

io_dev_to_node() returns a token corresponding to the specified dev_t dev_type. See mknod(5).

Arguments

dev

dev_t to map to node.

dev_type

Possible values are:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

Return Value

Token - Upon success.
NULL - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_NODE_NOEXIST

IO_E_SYSCALL

libIO FUNCTION

Name

io_hw_compare() - compares two pre-HP-UX 11i V3 hardware path structures

Synopsis

int io_hw_compare(leg_hw_path_t *path1, leg_hw_path_t *path2);

Description

io_hw_compare() compares contents of two leg_hw_path_t structures. If found equivalent, returns success; otherwise, returns an error. leg_hw_path_t is a pre-HP-UX 11i V3 structure used for storing hardware paths.

Arguments

path1, path2: Pointers to leg_hw_path_t structures.

Return Value

IO_SUCCESS - If found equivalent.
IO_ERROR - Not equivalent.

Errors

None.

libIO FUNCTION

Name

io_hw_compare_ext() - compares two hardware path structures used on HP-UX 11i V3 or later

Synopsis

int io_hw_compare_ext(hw_path_t *path1, hw_path_t *path2);

Description

io_hw_compare_ext() compares contents of two hw_path_t structures. If found equivalent, returns success; otherwise, returns an error. hw_path_t is a hardware path structure used on HP-UX 11i V3 or later.

Arguments

path1, path2: Pointers to hw_path_t structures.

Return Value

IO_SUCCESS - If found equivalent.
IO_ERROR - Not equivalent.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_NODE_NOEXIST

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_hw_path_to_node() - converts a hardware path to token

Synopsis

io_token_t io_hw_path_to_node(hw_path_t *hw_path);

Description

io_hw_path_to_node() returns the token for the specified hardware path.

Arguments

hw_path: Pointer to hardware path.

Return Value

Token - Upon success.
NULL - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_NODE_NOEXIST

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_hw_path_to_str() - converts a hardware path to a string

Synopsis

int io_hw_path_to_str(char *str,hw_path_t *hw_path);

Description

io_hw_path_to_str() converts the hardware path specified by hw_path to the string pointed to by str. str must have enough space (maximum hardware path length - MAX_HW_PATH_STR) to hold the converted string. If str is NULL, then no data is transferred, 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 my_node:

hw_path_t hw_path; 
char my_string[MAX_HW_PATH_STR]; 
if (io_init(O_RDWR) == -1) exit(1); 
io_node_to_hw_path(my_node,&hw_path); 
io_hw_path_to_str(my_string,&hw_path); 
printf("%s", my_string); 
io_end(); 
exit(0); 

Return Value

Number of bytes in the string - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_str_to_hw_path() - converts a string representing the hardware path to hw_path_t structure

Synopsis

int io_str_to_hw_path(char *str,hw_path_t *hw_path);

Description

io_str_to_hw_path() 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

char *str_path="4/16.4.0"

hw_path_t hw_path;

if (io_init(O_RDWR) == -1) exit(1);

io_str_to_hw_path(str_path, &hw_path);

io_end();

exit(0);

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_PATH_STR

IO_E_SYSCALL

libIO FUNCTION

Name

io_is_option_set() - determines if the option(s) is set for dev_t

Synopsis

int io_is_option_set(dev_t dev, int dev_type, char *options);

Description

io_is_option_set() calls io_mkdev() 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

dev_t to check for option settings.

dev_type

Possible values are:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

options

NULL terminated string indicating device specific options.

Return Value

1 - If one or more of specified options set.
IO_ERROR - Otherwise.

Errors

None.

libIO FUNCTION

Name

io_mkdev() - builds a dev_t, given a node and option string

Synopsis

int io_mkdev(io_token_t node,int dev_type,char *options,dev_t *dev);

Description

io_mkdev() builds a dev_t 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:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

dev

Pointer to dev_t.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_NODE_NOEXIST

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_node_to_hw_path() - converts token to a hardware path

Synopsis

int io_node_to_hw_path(io_token_t node,hw_path_t *hw_path);

Description

io_node_to_hw_path() 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

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_NODE_NOEXIST

IO_E_SYSCALL

libIO FUNCTION

Name

io_query() - gets information about a token

Synopsis

int io_query(io_token_t token,int type,char *key,void *ptr);

Description

io_query() is used to get information about a token previously obtained by a call to io_search(). 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 io_query() just returns the number of bytes which would have been copied. See the examples in io_search().

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 io_search().

type

Specifies type of query.

Only one should be specified. The defined values are:

S_IOTREE: Causes a query of the I/O tree.
S_IOTREE_EXT: Causes a query of the agile I/O tree.
S_BDEVSW: Causes a query of a block device switch table.
S_CDEVSW: 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.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_KEY_TOKEN_DEF

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_query_batch() - creates multiple keys to call io_query_array()

Synopsis

int io_query_batch(io_token_t token, int type, char *key1, 
                   void *dat1,char *key2, void *dat2, ..., 
                   char *keyN,void *datN,NULL); 

Description

This routine copies the key/dat arguments (one or more pair) into an array and calls io_query_array() with the passed search parameters.

Arguments

token: Token returned by previous call to io_search().
type: Specifies type (see io_query()).
key: Query field string.
dat: Query field data.

Return Value

See Return Value section of io_query_array().

Errors

See the Errors section of io_query_array().

libIO FUNCTION

Name

io_query_array() - gets information (multiple fields) about a token

Synopsis

int io_query_array(io_token_t token, int type, 
                   int nkeys, char *key[], void *ptr[]); 

Description

This routine is an enhancement to io_query(). It returns multiple fields for a token at one time.

Arguments

token: Token returned by previous call to io_search().
type: Type of query (see io_query()).
nkeys: Number of keys in the query.
key[ ]: An array of query field string.
ptr[ ]: An array of corresponding query field data.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_DCONF_ACCESS

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_search(), io_search_array() - searches I/O subsystem and system data structures

Synopsis

io_token_t io_search(io_token_t token, int type, int qual, 
                     char *key1, void *dat1, char *key2, void *dat2,..., 
                     char *keyN, void *datN,NULL); 

io_token_t io_search_array(io_token_t token, int type, int qual, 
                           char *key[], void *dat[]); 

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 io_query() command to obtain information about the token.

Arguments

token

Token returned by a previous call to io_search(), or NULL if first search.

type

Specifies type of search (see io_query()).

qual

Qualifiers for search. More than one may be specified by bitwise "ORing" values into qual. Defined values are:

Q_SW: Software is associated with the I/O tree node.
Q_HW: Hardware is associated with I/O tree node.
Q_PSEUDO: Is a pseudo device driver.
Q_DEVSW: Has switch table entry points.
Q_SUBTREE: On I/O tree searches, return entire subtree under matching node.
Q_NEW: Newly found hardware.
Q_TRANS: Allows transparent nodes to be returned.
Q_CONSOLE: Matches console device.
Q_DUMP: Matches dump devices.
Q_BOOT: Matches boot device.
Q_ROOT: Matches root filesystem devices.
Q_SWAP: Matches swap devices.
Q_SAVE_CONF: I/O tree node information saved in ioconfig files. (See ioconfig(4)).

key

A string corresponding to a defined query field. For io_search_array(), this is a NULL terminated array of strings.

IO_MAX_SEARCH_KEYS 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. IO_MAX_DATA_SIZE is the maximum data size.

Return Value

token - Upon success.
NULL - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_KEY_TOKEN_DEF

IO_E_MATCH

IO_E_MEM_ALLOC

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_search_array_batch() - retrieves an array of token matching the search

Synopsis

io_search_array_batch (io_token_t token, int type, int qual, 
                       char *key[],void *dat[],io_token_t *ret_token); 

Description

This routine is an enhancement of io_search_array(), it returns an array of tokens.

Arguments

token

Token returned by previous call to io_search(), or NULL if first search.

type

Specifies type of search (see io_query()).

qual

Qualifier for search (see io_search()).

key[] An array of query field string.

dat[]

An array of corresponding query field data.

ret_roken[]

An array of token returned.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_NODE_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_mkdev_ext() - returns a dev_t for the given node, dev_type, and device options

Synopsis

int io_mkdev_ext(io_token_t node, int dev_type, uint64_t options, 
                 dev_t *dev); 

Description

io_mkdev_ext() builds a dev_t from the given node, device type and options. This API is for creating a dev_t for an agile node only. io_errno is set to IO_E_FUNC_NOT_SUPPORTED if called on legacy nodes.

Arguments

node

Token corresponding to the I/O node.

dev_type

Possible values are:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

options

Device specific options.

dev

The created dev_t is stored in memory pointed to by dev.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

IO_E_NODE_NOEXIST

IO_E_FUNC_NOT_SUPPORTED

libIO FUNCTION

Name

io_dev_to_options() - returns the device options of a given dev_t and dev_type

Synopsis

int io_dev_to_options(dev_t dev, int dev_type, uint64_t *options);

Description

Given dev_t and dev_type, io_dev_to_options() returns its device options in a uint64_t bit mask format.

Arguments

dev

dev_t value to retrieve the device options.

dev_type

Possible values are:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

options

Unsigned 64-bit mask representing the device options is stored in the location pointed to by options.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Failure. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

libIO FUNCTION

Name

io_is_legacy_dev() - determines if the given dev_t is legacy

Synopsis

int io_is_legacy_dev(dev_t dev, int dev_type);

Description

This API determines if the given dev_t is a legacy or an agile dev_t. While checking if a given device special file is persistent or legacy, issue a stat() call on the device special file and pass st_rdev (see stat(2)) to this API. The device special file is of persistent type if the API returns IO_TOKEN_NEW and the file is of legacy type if the API returns IO_TOKEN_LEGACY.

Arguments

dev

dev_t of the I/O node.

dev_type

Possible values are:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

Return Value

IO_TOKEN_NEW - If dev_t is of an agile I/O node.
IO_TOKEN_LEGACY - If dev_t is of a legacy I/O node.
IO_ERROR - Failure. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

libIO FUNCTION

Name

io_is_legacy_token() - determines if token is legacy or agile

Synopsis

int io_is_legacy_token(io_token_t token);

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

IO_TOKEN_NEW - If dev_t is of an agile node.
IO_TOKEN_LEGACY - If dev_t is of a legacy node.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

libIO FUNCTION

Name

io_get_legacy_mode() - returns the state of legacy mode

Synopsis

int io_get_legacy_mode (unsigned int *mode) 

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 currently 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

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_ACCESS

IO_E_DCONF_OPEN

IO_E_FUNC_NOT_SUPPORTED

libIO FUNCTION

Name

io_get_mapping() - returns a mapping between a given node and other I/O nodes

Synopsis

int io_get_mapping(io_token_t node, io_map_type_t map_type, 
                   int *count, io_token_t *token_arry); 

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 IO_LEGACY_2_NEW, the routine will return an agile token mapped to it.

Given an agile token with a map_type of IO_NEW_2_LEGACY, the routine will return one or more legacy token(s).

Given a LUN token with a map_type of IO_LUN_2_LUNPATH, the routine will return one or more lunpath token(s) mapped to it.

Likewise, if given a lunpath token and a map_type of IO_LUNPATH_2_LUN, a LUN token will be returned.

Arguments

node

A node token to which mappings will be returned.

map_type

Possible values are:

IO_LEGACY_2_NEW: Obtains the agile node token from the given legacy token. This is a one to one mapping.
IO_NEW_2_LEGACY: Obtains the legacy node token from the given agile node token. This can be a one to many mapping.
IO_LUN_2_LUNPATH: Obtains the lunpath token from the given lun node token. This can be a one to many mapping.
IO_LUNPATH_2_LUN: Obtains the lun node token from the given lunpath token. This mapping is a one to one mapping.

token_arry

Possible values are:

INPUT:

A pointer to an array of io_token_t. Recommended size is:

(sizeof(io_token_t)*10)

OUTPUT:

The io_token_t(s) returned will be copied into this array.

count

The values are:

INPUT:

Number of tokens to be returned in the token_array.

10 is the recommended for the initial count.

OUTPUT:

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 IO_ERROR,

4)

io_errno will be set to IO_E_BUF_TOO_SMALL.

In this case, the caller needs to allocate a bigger buffer after recalculating it using:

(sizeof(io_token_t)*count)

with the returned count value. and needs to call the API again with the new buffer and count values.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_NODE_NOEXIST

IO_E_SYSCALL

IO_E_BUF_TOO_SMALL

IO_E_MEM_ALLOC

libIO FUNCTION

Name

io_is_hwpath_legacy() - determines if the given hardware path is of legacy or agile form

Synopsis

int io_is_hwpath_legacy(char *path);

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

IO_HWPATH_NEW - If the path is an agile path.
IO_HWPATH_LEGACY - If the path is a legacy path.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_SYSCALL

IO_E_PATH_STR

IO_E_NODE_NOEXIST

libIO FUNCTION

Name

io_get_node_relation() - retrieves a relative of a given node token

Synopsis

int io_get_node_relation(io_token_t node, int relationship, 
                         uint64_t addr, io_token_t *relative); 

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:

IO_REL_CHILD
IO_REL_PARENT
IO_REL_SIBLING

The node token of the relative is returned in the parameter relative. If either IO_REL_CHILD or IO_REL_SIBLING 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 particular 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:

IO_REL_CHILD: Look for a child node.
IO_REL_PARENT: Look for the parent node.
IO_REL_SIBLING: 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

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_SYSCALL

libIO FUNCTION

Name

io_legacy_to_new_hwpath() - 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

int io_legacy_to_new_hwpath (leg_hw_path_t *from, hw_path_t *to);

Description

io_legacy_to_new_hwpath() converts a pre-HP-UX 11i V3 hardware path (leg_hw_path_t) data structure to the hardware path for HP-UX 11i V3 or later (hw_path_t).

Arguments

from: Pointer to a leg_hw_path_t data structure.
to: A pointer to the hw_path_t data structure.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_PARM

libIO FUNCTION

Name

io_new_to_legacy_hwpath() - 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

int io_new_to_legacy_hwpath (hw_path_t *from, leg_hw_path_t *to);

Description

io_new_to_legacy_hwpath() converts a hardware path used on HP-UX 11i V3 or later (hw_path_t) data structure to the pre-HP-UX 11i V3 hardware path (leg_hw_path_t). If hw_path_t has more than 14 elements or any of them is more than 8 bit long, the API will set io_errno to IO_E_PARM.

Arguments

from: Pointer to hw_path_t data structure.
to: A pointer to the legacy leg_hw_path_t data structure.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_PARM

libIO FUNCTION

Name

io_get_devs() - returns the dev_ts of a given node

Synopsis

int io_get_devs(io_token_t node, io_dev_info_t *dev_arry, int *count);

Description

io_get_devs() gets all the dev_ts (including char and block dev_ts) of a given node. It will return all the dev_ts, the device specific options and the dev_t type in dev_arry. The dev_type field of dev_arry is updated to say if the dev_t type is D_CHR (character) or D_BLK (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_ts.

dev_arry

Possible values are:

INPUT:: A pointer to an array of io_dev_info_t. The array is allocated by the caller. The initial size can be IO_MAX_DEVS_IN_IOQ (this is currently set to 48).
OUTPUT:: The io_dev_info_t returned will be copied into this array.

count

Possible values are:

INPUT:

Number of io_dev_info_t expected. Should be set to IO_MAX_DEVS_IN_IOQ initially.

OUTPUT:

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 IO_ERROR.

4)

io_errno will be set to IO_E_BUF_TOO_SMALL.

In this case, the caller needs to allocate a bigger buffer after recalculating it using:

(sizeof(io_dev_info_t)*count)

with the returned count value. and needs to call the API again with the new buffer and count values.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_NODE_NOEXIST

IO_E_DCONF_ACCESS

IO_E_SYSCALL

IO_E_MEM_ALLOC

IO_BUF_TOO_SMALL

libIO FUNCTION

Name

io_block_to_raw() - returns the character dev_t of the given block dev_t

Synopsis

int io_block_to_raw(dev_t bdev, dev_t *rdev);

Description

This API is used to retrieve character dev_t corresponding to the block dev_t.

Arguments

bdev

Block dev_t whose character dev_t is needed.

rdev

The retrieved character dev_t of the given block dev_t is stored here through the pointer.

NODEV in case of an error.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_SYSCALL

IO_E_DCONF_ACCESS

libIO FUNCTION

Name

io_block_to_char_dsf() - maps a block device special file to character device special file

Synopsis

int io_block_to_char_dsf(char *block_dsf, char *char_dsf);

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 MAXPATHLEN.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

IO_E_BUF_TOO_SMALL

libIO FUNCTION

Name

io_char_to_block_dsf() - map a char device special file to block device special file

Synopsis

int io_char_to_block_dsf(char *char_dsf, char *block_dsf);

Description

This API maps a given character device special file to its corresponding 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 MAXPATHLEN.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

IO_E_BUF_TOO_SMALL

libIO FUNCTION

Name

io_raw_to_block() - returns the block dev_t of the given character dev_t

Synopsis

int io_raw_to_block(dev_t rdev, dev_t *bdev);

Description

This API is used to retrieve block dev_t corresponding to the character dev_t.

Arguments

rdev: Character dev_t whose block dev_t is needed.
bdev: The retrieved block dev_t of the given character dev_t is stored here through the pointer. NODEV in case of an error.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_SYSCALL

IO_E_DCONF_ACCESS

libIO FUNCTION

Name

io_legacy_to_new_dev() - maps a legacy dev_t to an agile dev_t

Synopsis

int io_legacy_to_new_dev(dev_t legacy_dev, int dev_type, 
                         dev_t *new_dev); 

Description

Given a legacy dev_t and dev_type, this API retrieves its agile dev_t.

Arguments

legacy_dev

Legacy dev_t to retrieve the agile dev_t.

dev_type

Possible values are:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

new_dev

The agile dev_t is stored here.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

libIO FUNCTION

Name

io_legacy_to_new_dsf() - maps a legacy device special file to a persistent device special file

Synopsis

int io_legacy_to_new_dsf(char *legacy_dsf, char *new_dsf);

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 corresponding persistent device special file.
new_dsf: A pointer to a buffer of length MAXPATHLEN.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

IO_E_MATCH

IO_E_BUF_TOO_SMALL

libIO FUNCTION

Name

io_new_to_legacy_devs() - maps an agile dev_t to one or more legacy dev_t(s)

Synopsis

int io_new_to_legacy_devs(dev_t new_dev, int dev_type, dev_t *dev_arry, 
                          int *count); 

Description

This API maps an agile dev_t to its legacy dev_t(s). There can be one to many mappings.

Arguments

new_dev

A pointer to the agile dev_t to obtain its corresponding legacy dev_ts.

dev_type

Possible values are:

D_CHR: Character dev_t.
D_BLK: Block dev_t.

dev_arry

Possible values are:

INPUT:

A pointer to an array of legacy dev_ts. The array is allocated by the caller with a recommended initial size of:

(IO_MAX_DEVS_IN_IOQ * sizeof (dev_t))

OUTPUT:

The dev_ts returned will be copied into this array.

count

Possible values are:

INPUT:

Number of legacy dev_ts expected (recommended MAX_DEVS_IN_IOQ (48)).

OUTPUT:

Number of legacy dev_ts 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 dev_t to be returned.

3)

The API will return IO_ERROR.

4)

io_errno will be set to IO_E_BUF_TOO_SMALL.

In this case, the caller needs to allocate a bigger buffer after recalculating it using:

(sizeof (dev_t)*count)

with the returned count value. and needs to call the API again with the new buffer and count values.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

IO_E_BUF_TOO_SMALL

IO_E_MEM_ALLOC

libIO FUNCTION

Name

io_new_to_legacy_dsfs() - maps a agile device special file to one or more legacy device special file

Synopsis

int io_new_to_legacy_dsfs(char *new_dsf, char *legacy_dsf,int *count);

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:

INPUT:: 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 (MAXPATHLEN *10) and the count should be set to 10.
OUTPUT:: 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:

INPUT:

Number of legacy device special files expected. Initial size should be 10.

OUTPUT:

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 IO_ERROR.

4)

io_errno will be set to IO_E_BUF_TOO_SMALL.

In this case, the caller needs to allocate a bigger buffer after recalculating it

(MAXPATHLEN)*count)

with the returned count value. and needs to call the API again with the new buffer and count values.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise. io_errno is set to indicate the error.

Errors

IO_E_DCONF_OPEN

IO_E_PARM

IO_E_DCONF_ACCESS

IO_E_SYSCALL

IO_BUF_TOO_SMALL

IO_E_MEM_ALLOC

libIO FUNCTION

Name

io_init_hw_path() - initializes the hardware path with the passed flags argument

Synopsis

int io_init_hw_path(hw_path_t *hw_path, int flags);

Description

This API initializes the hardware path structure hw_path_t according to the specified flags argument. IO_TREE_LEGACY should be passed as flags value when initializing 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 IO_TREE_LEGACY.

Return Value

IO_SUCCESS - Upon success.
IO_ERROR - Otherwise.

Errors

None.

LIBIO_ERRORS

The following describes the io_errno values, which are set after a libIO API failure.

IO_E_BUF_TOO_SMALL: User buffer too small.
IO_E_DCONF_ACCESS: /dev/config permission denied.
IO_E_DCONF_NOEXIST: /dev/config does not exist.
IO_E_DCONF_OPEN: /dev/config is not open.
IO_E_DYN_MAJOR:: Dynamic major not defined for specified node.
IO_E_FUNC_NOT_SUPPORTED: Functionality not supported.
IO_E_KEY_TOKEN_DEF: Key is undefined for specified token, or token is NULL.
IO_E_MATCH: No match found.
IO_E_MEM_ALLOC: Unable to allocate memory.
IO_E_NO_LCK: Another IO event is in progress.
IO_E_NODE_DESTROY: Not able to destroy specified node or a descendent of node.
IO_E_NODE_NOEXIST: I/O tree node does not exist.
IO_E_NODE_PARM: Node already exists or parameter error detected.
IO_E_OPER_FAIL: Operation failed.
IO_E_OPEN_FLAG: Invalid open flag.
IO_E_PARM: Parameter error.
IO_E_PATH_STR: String does not represent a valid path.
IO_E_SYSCALL: System call error.
IO_E_UNEXPECTED: Unexpected error.
IO_E_WOULDBLOCK: The call would block in the kernel.

MULTITHREAD USAGE

The libIO APIs are not thread-safe.

WARNINGS

Many APIs in libIO are release specific. These APIs may be removed or have its meaning changed in future releases of HP-UX.

AUTHOR

libIO was developed by HP.

FILES

/usr/include/sys/libIO.h: libIO data structures and identifiers.
/usr/lib/libIO.sl: libIO 32 bit for PA-RISC systems.
/usr/lib/pa20_64/libIO.sl: libIO 64 bit for PA-RISC systems.
/usr/lib/hpux32/libIO.so: libIO 32 bit for Itanium-based systems.
/usr/lib/hpux64/libIO.so: libIO 64 bit for Itanium-based systems.

libIO(3X)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

Remarks

DESCRIPTION

I/O Subsystem Terms

LibIO APIs

libIO FUNCTION

Name

Synopsis

Description

Arguments

Example

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Example

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Example

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description

Arguments

Return Value

Errors

libIO FUNCTION

Name

Synopsis

Description