#ident "@(#)libhotplug.3lib.txt.changebar 1.9 09/08/21 SMI" Interface Libraries libhotplug(3LIB) NAME libhotplug - hotplug management library SYNOPSIS cc [ flag... ] file... -lhotplug [ library... ] #include DESCRIPTION Functions in this library manage hotplug connectors and ports. Hotplug information is organized as a graph of nodes, defined as hp_node_t in the libhotplug interfaces. Each hp_node_t represents a physical hotplug connector, a virtual hotplug port, an associated device node, or a description of how the associated resources are consumed. The types of data associated with each node are: o Name o Type (connector, port, device, or usage) o The current state of the node o Description of associated resource usage All hotplug nodes have a set of common attributes, such as a name and type. But only connector and port nodes have a current state. And only usage nodes have a description of resource usage. The library provides functions to access each of these data fields from an hp_node_t node. Fields that do not apply fail with an error code. Using libhotplug involves three steps: o Creating a snapshot of the hotplug information o Traversing the snapshot to get information of interest and/or initiate command operations o Destroying the snapshot of the hotplug information A snapshot of the hotplug information is created by calling hp_init(3HOTPLUG) and destroyed by calling hp_fini(3HOTPLUG). An application can specify the data to be included in the snapshot (full or partial information, include or exclude the verbose usage descriptions) and get a handle to the root of the snapshot. See hp_init(3HOTPLUG) for details. The application then traverses the snapshot to obtain data about hotplug connectors, ports, and their dependents. Or to perform commands on specific hotplug connectors or ports. The snapshot is normally traversed through parent-child-sibling linkage. Each node contains references to its parent, its next sibling, and its first child. An application can traverse the snapshot by manually following these linkages. The library functions hp_parent(3HOTPLUG), hp_sibling(3HOTPLUG), and hp_child(3HOTPLUG) access the links from an hp_node_t node. Alternatively, the library function hp_traverse(3HOTPLUG) can be used with an application-specific callback function to do an automated traversal of the snapshot. The callback function will be executed on each node visited during a child first traversal from a specified hp_node_t node in the snapshot. INTERFACES The shared object libhotplug.so.1 provides the public interfaces defined below. See Intro(3) for additional information on shared object interfaces. hp_init hp_fini hp_traverse hp_parent hp_sibling hp_child | hp_name hp_path | hp_type hp_state | hp_usage hp_description | hp_last_change hp_set_state | hp_set_private hp_get_private | EXAMPLES | Example 1: Information accessible through libhotplug interfaces | | The following example illustrates the kind of information that | is accessible through libhotplug interfaces for a system that | has physical and virtual hotplug capabilities: | | Physical Configuration: | | Four physical PCI hotplug connectors. | | One PCI card that is a USB controller. | | One PCI card that is a LAN controller. | | One USB storage device attached to the USB controller. | | Logical Configuration: | | One network address (10.0.0.1) plumbed on the LAN controller. | | One filesystem ("/") mounted on the USB storage device. | | Hotplug Information Snapshot: | | +-> Type: HP_NODE_CONNECTOR | | Name: pci.1.0 | | Path: /pci@0 | | State: Enabled | | | | | +-> Type: HP_NODE_PORT | | Name: pci0,0 | | Path: /pci@0 | | State: Operational | | | | | +-> Type: HP_NODE_DEVICE | | Name: usb@0,0 | | Path: /pci@0/usb@0,0 | | | | | +-> Type: HP_NODE_DEVICE | | Name: storage@2 | | Path: /pci@0/usb@0,0/storage@2 | | | | | +-> Type: HP_NODE_DEVICE | | Name: disk@0,0 | | Path: /pci@0/usb@0,0/storage@2/disk@0,0 | | | | | +-> Type: HP_NODE_USAGE | | Name: /dev/dsk/c0t0d0s0 | | Description: mounted filesystem "/" | | | +-> Type: HP_NODE_CONNECTOR | | Name: pci.2.0 | | State: Enabled | | | | | +-> Type: HP_NODE_PORT | | Name: pci1,0 | | Path: /pci@1 | | State: Operational | | | | | +-> Type: HP_NODE_DEVICE | | Name: network@0 | | Path: /pci@1/network@0 | | | | | +-> Type: HP_NODE_USAGE | | | Name: /devices/pci@1/network@0 | | | Description: Network interface e1000g1 | | | | | +-> Type: HP_NODE_USAGE | | Name: SUNW_datalink/2 | | Description: e1000g1: hosts IP addresses: 10.0.0.1 | | | +-> Type: HP_NODE_CONNECTOR | | Name: pci.3.0 | | Path: /pci@2 | | State: Empty | | | +-> Type: HP_NODE_CONNECTOR | Name: pci.4.0 | Path: /pci@3 | State: Empty | FILES /lib/libhotplug.so.1 shared object | /usr/lib/amd64/libhotplug.so.1 | | 64-bit shared object (x86) | | /usr/lib/sparcv9/libhotplug.so.1 | | 64-bit shared object (SPARC) ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWcsl (32-bit) | | | SUNWcslx (64-bit) | |_____________________________|_____________________________| | Interface Stability | Consolidation Private | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| SEE ALSO hp_init(3HOTPLUG), hp_name(3HOTPLUG), hp_traverse(3HOTPLUG), | hp_set_state(3HOTPLUG), hp_set_private(3HOTPLUG) Hotplug Information Library Functions hp_init(3HOTPLUG) NAME hp_init, hp_fini - create and destroy a snapshot of hotplug information SYNOPSIS cc [ flag... ] file... -lhotplug [ library... ] #include hp_node_t hp_init(const char *path, const char *connection, uint_t flags); void hp_fini(hp_node_t root); PARAMETERS flags Snapshot content specification. The possible | values can include: | | HPINFOUSAGE Include verbose usage nodes. path Physical path of the root device node of the snapshot. connection Physical hotplug connector, or virtual hotplug port associated with the specified physical path. root Handle obtained by calling hp_init(). DESCRIPTION The hp_init() function creates a snapshot of hotplug information and returns a handle of the root of the snapshot. The caller may specify the contents of the snapshot by providing flags, a path, and a connector. Specifying a NULL connection will get a snapshot of all the hotplug connectors and ports immediately descended from the specified path. The hp_fini() function destroys a snapshot of hotplug information and frees the associated memory. All handles associated with this snapshot become invalid after the call to hp_fini(). RETURN VALUES Upon success, hp_init() returns a handle. Otherwise, NULL is returned and errno is set to indicate the error. ERRORS The hp_init() function may set errno to one of the following: EACCES Insufficient privilege for accessing hotplug data. | EBADF The hotplug service is not available. | ENOENT The path or connection is not present in the system. EINVAL The path or connection is improperly formatted, or invalid flags were specified. ENOMEM Insufficient memory to create the snapshot. EXAMPLES Example 1: Using the libhotplug Interfaces To Print All Connections The following is an example using the libhotplug interfaces to print all of the hotplug connections defined in the system. /* * Code to print all hotplug connection names */ #include #include int print_connection_name(hp_node_t node, void *arg) { printf("%s\n", hp_name(node)); return (HP_WALK_CONTINUE); } main() { hp_node_t root_node; | if((root_node = hp_init("/", NULL, 0)) == NULL) { fprintf(stderr, "hp_init() failed (%s)\n"); exit(1); } hp_traverse(root_node, NULL, print_connection_name); hp_fini(root_node); } ATTRIBUTES See attributes(5) for descriptions of the following attributes: ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Interface Stability | Consolidation Private | |_____________________________|_____________________________| | MT-Level | Safe | |_____________________________|_____________________________| SEE ALSO hp_name(3HOTPLUG), hp_traverse(3HOTPLUG), libhotplug(3LIB), | hp_set_state(3HOTPLUG), hp_set_private(3HOTPLUG), attributes(5) Hotplug Information Library Functions hp_name(3HOTPLUG) NAME | hp_name, hp_path, hp_type, hp_description, hp_state, hp_usage, | hp_last_change, hp_parent, hp_child, hp_sibling, - return | libhotplug node information SYNOPSIS cc [ flag... ] file... -lhotplug [ library... ] #include | #include char *hp_name(hp_node_t node); | int hp_path(hp_node_t node, char *path, char *connection); | int hp_type(hp_node_t node); char *hp_description(hp_node_t node); int hp_state(hp_node_t node); char *hp_usage(hp_node_t node); | time_t hp_last_change(hp_node_t node); | hp_node_t hp_parent(hp_node_t node); hp_node_t hp_child(hp_node_t node); hp_node_t hp_sibling(hp_node_t node); PARAMETERS node A handle to a hotplug information node. | path A buffer of MAXPATHLEN length provided by the | caller to retrieve the full path of a hotplug | information node. | | connection A buffer of MAXPATHLEN length provided by the | caller to retrieve the connection name of a | hotplug information node. DESCRIPTION These functions extract information associated with a hotplug information node. RETURN VALUES The hp_name() function returns a pointer to the name of the hotplug information node. | The hp_path() function returns the full path name and connection | name (if applicable) of a hotplug information node. The caller | must supply pre-allocated buffers of at least MAXPATHLEN length. | | The hp_type() function returns one of the following symbolic | constants which indicates what type of node it is: | | HP_NODE_NONE Not a valid node. | | HP_NODE_CONNECTOR Physical hotplug connector. | | HP_NODE_PORT Virtual hotplug port. | | HP_NODE_DEVICE Device node. | | HP_NODE_USAGE Verbose usage information node. The hp_description() function returns a string describing what type of node it is. This function is only applicable to connector nodes. Example descriptions include "PCI Slot", "PCI Express Slot", etc. The hp_state() function returns an integer indicating the current state of a hotplug connection. This function is only applicable to connector and port nodes, and fails for any other type of node. A failure is indicated by a return value of -1 and errno is set to EINVAL. The hp_usage() function returns a pointer to a description of detailed resource usage associated with a hotplug information node. It only applies to usage nodes, and fails for any other type of node. A failure is indicated by a return value of NULL and errno is set to EINVAL. | The hp_last_change() function returns a time stamp indicating | when the state of a hotplug connection was last changed. This | function is only applicable to connector and port nodes, and fails | for any other type of node. A failure is indicated by a return | value of (time_t)-1 and errno is set to EINVAL. | The hp_parent(), hp_child(), and hp_sibling() functions return a handle to the hp_node_t that is the information node's parent, first child, or next immediate sibling respectively. If the hotplug node does not have a parent, child, or sibling then a NULL is returned. ATTRIBUTES See attributes(5) for descriptions of the following attributes: _________________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|__________________________________| | Interface Stability | Consolidation Private | |_____________________________|__________________________________| | MT-Level | Safe | |_____________________________|__________________________________| SEE ALSO hp_init(3HOTPLUG), hp_traverse(3HOTPLUG), libhotplug(3LIB), | hp_set_state(3HOTPLUG), hp_set_private(3HOTPLUG), attributes(5) Hotplug Information Library Functions hp_traverse(3HOTPLUG) NAME hp_traverse - traverse a hotplug information snapshot SYNOPSIS cc [ flag... ] file... -lhotplug [ library... ] #include #define HP_WALK_CONTINUE 0 #define HP_WALK_PRUNECHILD 1 #define HP_WALK_PRUNESIBLING 2 #define HP_WALK_TERMINATE 3 int hp_traverse(hp_node_t root, void *arg, int(*hp_callback)(hp_node_t node, void *arg)); PARAMETERS root A handle to a hotplug information node which will be the root of the traversal. arg A private, application specific aargument that will be passed as a parameter to the callback function. hp_callback A private, application specific callback function which will be called for each node as it is visited in the traversal. DESCRIPTION This function performs an automated traversal of a branch of a hotplug information snapshot. It executes the user supplied callback function upon each hotplug information node. The callback function can return any of the defined return values each time it is called. A description is as follows: HP_WALK_CONTINUE Continue normally to the next node. HP_WALK_PRUNECHILD Continue the traversal, but skip all child nodes of the current node. HP_WALK_PRUNESIBLING Continue the traversal, but skip all siblings of the current node and all their children. RETURN VALUES The hp_traverse() function returns a 0 upon success, or on failure it returns -1 and sets an errno value. Possible errno values are: EINVAL The caller supplied invalid arguments. ATTRIBUTES See attributes(5) for descriptions of the following attributes: _________________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|__________________________________| | Interface Stability | Consolidation Private | |_____________________________|__________________________________| | MT-Level | Safe | |_____________________________|__________________________________| SEE ALSO hp_init(3HOTPLUG), hp_name(3HOTPLUG), libhotplug(3LIB), | hp_set_private(3HOTPLUG), attributes(5) Hotplug Information Library Functions hp_set_state(3HOTPLUG) NAME hp_set_state - initiate a state change operation on a hotplug node. SYNOPSIS cc [ flag... ] file... -lhotplug [ library... ] #include | int hp_set_state(hp_node_t root, uint_t flags, int state, | hp_node_t *resultsp); PARAMETERS root A handle to a hotplug information node which will be the root of the operation. flags State change operation flags. The possible values can be a bitwise OR of at least one of the following: HP_FORCE Use forced semantics. HP_QUERY Query the operation, and do not change system state. state The desired target state, to which the node will be transitioned. | resultsp A pointer to contain the results of the | operation. | DESCRIPTION This function initiates a state change operation on a specified branch of a hotplug information snapshot. It requests the transition of the specified root node and all of its dependents to the specified target state. If the specified flags include the HP_FORCE flag, then the operation will be performed with forced semantics. This flag should be used with extreme caution. If the specified flags include the HP_QUERY flag, then no actual state change will occur. The system will do a dry run of the specified operation, returning a prediction if the operation would succeed or fail. | If the operation fails, then a separate hotplug information | snapshot may be returned through the resultsp parameter. | The snapshot will include detailed usage information that | explains the reason for the failure if possible. It is | the caller's responsibility to free the results snapshot | with hp_fini(3HOTPLUG). | RETURN VALUES The hp_set_state() function returns a 0 upon success, or on | failure it returns an errno value. Possible errno values are: | | EACCES The caller is not authorized to perform the action. | | EBADF The hotplug service is not available. | EINVAL The caller supplied invalid arguments. ENOENT The caller specified a node which has no associated hotplug connectors or ports. | EBUSY The hotplug connector or port is busy. | EIO The operation failed in the kernel. ATTRIBUTES See attributes(5) for descriptions of the following attributes: _________________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|__________________________________| | Interface Stability | Consolidation Private | |_____________________________|__________________________________| | MT-Level | Safe | |_____________________________|__________________________________| SEE ALSO hp_init(3HOTPLUG), hp_name(3HOTPLUG), libhotplug(3LIB), | hp_traverse(3HOTPLUG), hp_set_private(3HOTPLUG), attributes(5) | | | Hotplug Information Library Functions hp_set_private(3HOTPLUG) | | NAME | hp_set_private, hp_get_private - set or get hardware private | functions of a hotplug node. | | SYNOPSIS | cc [ flag... ] file... -lhotplug [ library... ] | #include | | int hp_set_private(hp_node_t node, const char *options, | char **resultsp); | | int hp_get_private(hp_node_t node, const char *options, | char **resultsp); | | PARAMETERS | node A handle to a hotplug information node | which will be the target of the operation. | | options A string of hardware private functions or | options that will be sent to the bus specific | controller of the specified node. | | resultsp A pointer where a string of results from the | hardware private function will be returned. | | DESCRIPTION | The hp_set_private() function performs a bus specific command | on the bus controller associated with the specified hotplug | information node. The format and content of the options string | is completely hardware specific, but generally describes a function | and specific parameters. The options string conforms to the | getsubopt(3C) syntax convention. The results string is only | returned in the special case when the input options string was | the special value "help." In which case the results string | will conform to the getsubopt(3C) syntax convention, and will | indicate what options may be set with which possible values. | | The hp_get_private() function queries the current values of | bus specific properties from the bus controller associated with | the specified hotplug information node. The format and content | of the options string is completely hardware specific, but it | generally specifies which parameters are to be queried. The | values are returned through the resultsp parameter as a newly | allocated string. The results string conforms to the getsubopt(3C) | syntax convention. It is the caller's responsibility to free the | results string. | | | RETURN VALUES | The hp_set_private() and hp_get_private() functions return a 0 | upon success, or on failure they return an errno value. Possible | errno values are: | | EACCES The caller is not authorized to perform the action. | | EBADF The hotplug service is not available. | | EINVAL The caller supplied invalid arguments. | | ENOTSUP The caller specified a node which is not a hotplug | connector or port. | | EIO The operation failed in the kernel. | | | ATTRIBUTES | See attributes(5) for descriptions of the following attributes: | | _________________________________________________________________ | | ATTRIBUTE TYPE | ATTRIBUTE VALUE | | |_____________________________|__________________________________| | | Interface Stability | Consolidation Private | | |_____________________________|__________________________________| | | MT-Level | Safe | | |_____________________________|__________________________________| | | | SEE ALSO | hp_init(3HOTPLUG), hp_name(3HOTPLUG), libhotplug(3LIB), | hp_traverse(3HOTPLUG), hp_set_state(3HOTPLUG), attributes(5)