libIO.3x (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

libIO(3X) libIO(3X)

NAME

libIO: io_block_to_char_dsf(), io_block_to_raw(), io_char_to_block_dsf(), io_dev_to_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 sys-

tems), the program must link it using -lIO.

To use the

Threadsafe libIO library, libIOmt.so (for Itanium(R)-based systems) or libIOmt.sl

(for PA-RISC systems), the program must be compiled using -mt and -D_LIBIO_MT

ﬂags and link it

using

-lIOmt. (See the THREADSAFE LIBRARY section for more details).

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 speciﬁc error number when a

libIO API fails. The usage is similar to errno (see errno(2)).

dev_t Device identiﬁcation number. See mknod(5).

leg_hw_path_t A data structure for storing hardware paths used for releases prior to HP-UX

11i Version 3. 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 Version 3 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 Version 3:

io_block_to_char_dsf() Maps a block device special ﬁle to character device special ﬁle

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 ﬁle to block device special ﬁle

io_dev_to_dsf() Returns device special ﬁle corresponding to the given

dev_t.

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

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (24 pages)

PAGE 1
libIO(3X) libIO(3X) NAME libIO: io_block_to_char_dsf(), io_block_to_raw(), io_char_to_block_dsf(), io_dev_to_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_
PAGE 2
libIO(3X) A lA libIO(3X) 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 dri
PAGE 3
libIO(3X) libIO(3X) 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. Opens the /dev/config device special file, which causes an open (2) of the dev_config driver. io_init() io_init() must be called before calling any other routine in the libIO library.
PAGE 4
libIO(3X) libIO(3X) See the LIBIO_ERRORS section below for an explanation of each error value. The printed message has the form: str :libIO error message If str is NULL, the message has the form: libIO error message io_strerror() returns a pointer to the string containing the libIO error message which maps to the passed argument errnum .
PAGE 5
libIO(3X) libIO(3X) libIO FUNCTION Name io_dev_to_node() - converts a dev_t to token Synopsis #include 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_type dev_t to map to node . 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.
PAGE 6
libIO(3X) libIO(3X) 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.
PAGE 7
libIO(3X) libIO(3X) 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.
PAGE 8
libIO(3X) Arguments dev dev_type libIO(3X) dev_t to check for option settings. 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.
PAGE 9
libIO(3X) libIO(3X) 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 .
PAGE 10
libIO(3X) Arguments token libIO(3X) 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().
PAGE 11
libIO(3X) libIO(3X) 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: key 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.
PAGE 12
libIO(3X) libIO(3X) 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.
PAGE 13
libIO(3X) dev_type libIO(3X) 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.
PAGE 14
libIO(3X) libIO(3X) 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.
PAGE 15
libIO(3X) libIO(3X) 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.
PAGE 16
libIO(3X) libIO(3X) 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.
PAGE 17
libIO(3X) libIO(3X) 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).
PAGE 18
libIO(3X) libIO(3X) 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.
PAGE 19
libIO(3X) Arguments bdev rdev libIO(3X) Block dev_t whose character dev_t is needed. 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.
PAGE 20
libIO(3X) libIO(3X) 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 bdev Character dev_t whose block dev_t is needed. The retrieved block dev_t of the given character dev_t is stored here through the pointer.
PAGE 21
libIO(3X) libIO(3X) 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 new_dsf Legacy device special file to find its corresponding persistent device special file. A pointer to a buffer of length MAXPATHLEN. Return Value IO_SUCCESS - Upon success.
PAGE 22
libIO(3X) libIO(3X) 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.
PAGE 23
libIO(3X) libIO(3X) 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.
PAGE 24
libIO(3X) libIO(3X) [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. THREADSAFE LIBRARY The libIO APIs are threadsafe starting from HP-UX 11i Version 3 September 2008 Update.