libIO man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

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

       To use the library, (for Itanium(R)-based systems) or (for PA-RISC sys‐
       tems), the program must be compiled using and flags and link  it	 using
       (See the section for more details).

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

       Device identification number.
	      See mknod(5).

       A data structure for storing hardware paths used for releases
	      prior to HP-UX 11i Version 3.  This structure has only  14  ele‐
	      ments of type

       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

   LibIO APIs
       Here are the APIs provided for HP-UX 11i Version 3:

       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

       Returns device special file corresponding to the given

       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
       - returns device special file of a device corresponding to the given

   Synopsis
   Description
       This API returns a device special file corresponding to	the  specified
       This  API  will be faster than when the specified corresponds to either
       the default persistent or the legacy device special file of an existing
       device.	 See  devnm(3).	 Default device special files are those device
       special files which are created by (see insf(1M)).  This API  uses  the
       services of in case the given does not correspond to either the default
       persistent or the legacy device special file or the file	 that  is  not
       found on its default location.

   Arguments
	      dev_t	The corresponding to a device special file.

	      dev_type	The device special file type:

			for character special file.

			for block device file.

	      buffer	A  pointer  to	a  buffer to store the returned device
			special file.  The buffer is allocated by the  caller.
			By default, the size of the buffer should be

   Return Value
	      - Upon success.

	      - Otherwise.  is set to indicate the error.

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

   THREADSAFE LIBRARY
       The APIs are threadsafe starting from HP-UX  11i	 Version  3  September
       2008  Update.   The  library  is (for Itanium(R)-based systems) or (for
       PA-RISC systems).  Any program using the	 threadsafe  library  must  be
       compiled	 using	the and flags.	The program must link it using The and
       functions must be called from every thread.  These functions are neces‐
       sary, because thread local variables are used in and these thread local
       variables must be initialized in every thread before the is used.

       Note: A program cannot use the threadsafe and non-threadsafe  libraries
       together.

   Example of Using the Threadsafe Library
       The program specifies the threadsafe library as follows:

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

       Programs	 cannot	 use  the  threadsafe  and  non-threadsafe   libraries
       together.

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.

	      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), devnm(3) ioconfig(4), intro(7).

								     libIO(3X)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net