Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

io_get_mapping(3x) [hpux man page]

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_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
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 systems), the program must link it using I/O Subsystem Terms The following are some common I/O subsystem terminologies and structures used in this manpage. A handle used for uniquely identifying an object in I/O subsystem (represented 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 status 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 success; 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 success; 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 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 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 matching 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 mapping. 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 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 - 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: o o o 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 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: 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 hardware 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 currently 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 initially. 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 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 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 corresponding 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 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 - 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 recalculating 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 specified flags argument. should be passed as flags value when initial- izing 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)
Man Page