Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Thursday, June 13, 2019
 
 

libima (3LIB)

Name

libima - iSCSI Management API library

Synopsis

cc [ flag... ] file... -lima  [ library... ]
#include <ima.h>      // for IMA* library functions
#include <libsun_ima.h> // for SUN_IMA* library functions

Description

The functions in this library allow a management application to discover and manage the iSCSI resources through standard interfaces, they use an architecture that allows multiple iSCSI HBAs, sometimes referred to as hardware initiators, and/or multiple iSCSI software initiators installed on a system to provide a common interface to clients of the library.

INTERFACES

The shared object libima.so.1 provides the public interfaces defined below. For more information about shared object interfaces, see intro(3) man page.

IMA_AddDiscoveryAddress
IMA_AddLhbaMutualAuthParms
IMA_AddStaticDiscoveryTarget
IMA_DeregisterForObjectPropertyChanges
IMA_DeregisterForObjectVisibilityChanges
IMA_ExposeLu
IMA_FreeMemory
IMA_GenerateNodeName
IMA_GetAddressKeys
IMA_GetAssociatedPluginOid
IMA_GetConnectionOidList
IMA_GetConnectionProperties
IMA_GetDataDigestValues
IMA_GetDigestProperties
IMA_GetDataPduInOrderProperties
IMA_GetDataSequenceInOrderProperties
IMA_GetDefaultTime2RetainProperties
IMA_GetDefaultTime2WaitProperties
IMA_GetDeviceStatistics
IMA_GetDiscoveryAddressOidList
IMA_GetDiscoveryAddressProperties
IMA_GetDiscoveryProperties
IMA_GetErrorRecoveryLevelProperties
IMA_GetFirstBurstLengthProperties
IMA_GetHeaderDigestValues
IMA_GetIFMarkerProperties
IMA_GetIFMarkIntProperties
IMA_GetImmediateDataProperties
IMA_GetInitialR2TProperties
IMA_GetInitiatorAuthParms
IMA_GetInitiatorLocalAuthParms
IMA_GetInUseInitiatorAuthMethods
IMA_GetIpProperties
IMA_GetIpsecProperties
IMA_GetLhbaMutualAuthParmsList
IMA_GetLhbaOidList
IMA_GetLhbaProperties
IMA_GetLibraryProperties
IMA_GetLnpOidList
IMA_GetLnpProperties
IMA_GetLuOid
IMA_GetLuOidList
IMA_GetLuProperties
IMA_GetMaxBurstLengthProperties
IMA_GetMaxConnectionsProperties
IMA_GetMaxOutstandingR2TProperties
IMA_GetMaxRecvDataSegmentLengthProperties
IMA_GetMutualLocalAuth
IMA_GetMutualLocalAuthParms
IMA_GetNetworkPortalOidList
IMA_GetNetworkPortalProperties
IMA_GetNetworkPortStatus
IMA_GetNodeProperties
IMA_GetNonSharedNodeOidList
IMA_GetOFMarkerProperties
IMA_GetOFMarkIntProperties
IMA_GetObjectType
IMA_GetPhbaDownloadProperties
IMA_GetPhbaOidList
IMA_GetPhbaProperties
IMA_GetPhbaStatus
IMA_GetPluginOidList
IMA_GetPluginProperties
IMA_GetPnpOidList
IMA_GetPnpProperties
IMA_GetPnpStatistics
IMA_GetRadiusAccess
IMA_GetSessionOidList
IMA_GetSessionProperties
IMA_GetSharedNodeOid
IMA_GetStaticDiscoveryTargetOidList
IMA_GetStaticDiscoveryTargetProperties
IMA_GetStatisticsProperties
IMA_GetSupportedAuthMethods
IMA_GetTargetErrorStatistics
IMA_GetTargetOidList
IMA_GetTargetProperties
IMA_IsPhbaDownloadFile
IMA_LuInquiry
IMA_LuReadCapacity
IMA_LuReportLuns
IMA_PersistHbaParameters
IMA_PhbaDownload
IMA_PluginIOCtl
IMA_RegisterForObjectPropertyChanges
IMA_RegisterForObjectVisibilityChanges
IMA_RemoveDiscoveryAddress
IMA_RemoveLhbaMutualAuthParm
IMA_RemoveStaleData
IMA_RemoveStaticDiscoveryTarget
IMA_SetDataDigestValues
IMA_SetDataPduInOrder
IMA_SetDataSequenceInOrder
IMA_SetDefaultGateway
IMA_SetDefaultTime2Retain
IMA_SetDefaultTime2Wait
IMA_SetDnsServerAddress
IMA_SetErrorRecoveryLevel
IMA_SetFirstBurstLength
IMA_SetHeaderDigestValues
IMA_SetIFMarkerProperties
IMA_SetIFMarkIntProperties
IMA_SetImmediateData
IMA_SetInitialR2T
IMA_SetInitiatorAuthMethods
IMA_SetInitiatorAuthParms
IMA_SetInitiatorLocalAuthParms
IMA_SetIpConfigMethod
IMA_SetIsnsDiscovery
IMA_SetMaxBurstLength
IMA_SetMaxConnections
IMA_SetMaxRecvDataSegmentLength
IMA_SetMaxOutstandingR2T
IMA_SetMutualLocalAuth
IMA_SetMutualLocalAuthParms
IMA_SetNetworkPortalIpAddress
IMA_SetNodeAlias
IMA_SetNodeName
IMA_SetOFMarkerProperties
IMA_SetOFMarkIntProperties
IMA_SetRadiusAccess
IMA_SetSendTargetsDiscovery
IMA_SetSlpDiscovery
IMA_SetStaticDiscovery
IMA_SetStatisticsCollection
IMA_SetSubnetMask
IMA_UnexposeLu
SUN_IMA_SetTunableProperties
SUN_IMA_GetTunableProperties
SUN_IMA_GetSendTargetsList

Usage

Client applications link with the Common Library (using -lima) to access the interfaces. The Common Library dynamically loads an individual vendor-provided plugin library which is located in /etc/ima.conf on the host system.

Using libima involves the following steps:

  • Optionally calling the IMA_GetLibraryProperties() function to retrieve the properties of the Common Library.

  • Calling the IMA_GetPhbaOidList() function to get a list of the object IDs of all the physical HBAs in system.

  • Calling the IMA_GetLhbaOidList() function to get a list of the object IDs of all the logical HBAs in system

  • Optionally calling the IMA_GetPhbaProperties() function to get the general properties of a physical HBA.

  • Optionally calling the IMA_GetLhbaProperties() function to get the properties of the specified logical HBA.

  • Manage the discovery information and property information on HBAs and associated resources by calling the following:

    IMA_GetDiscoveryProperties()
    IMA_SetIsnsDiscovery()
    IMA_SetSlpDiscovery()
    IMA_SetStaticDiscovery()
    IMA_SetSendTargetsDiscovery()
    IMA_AddStaticDiscoveryTarget()
    IMA_RemoveStaticDiscoveryTarget()
  • Manage the network portal on HBAs and associated resources by calling:

    IMA_GetNetworkPortalOidList()
    IMA_GetNetworkPortalProperties()
    IMA_SetNetworkPortalIpAddress()
    IMA_GetLnpOidList()
    IMA_GetPnpOidList()
    IMA_GetLnpProperties()
    IMA_GetNetworkPortStatus()
    IMA_GetPnpOidList()
    IMA_GetNetworkPortStatus()
    IMA_GetPnpProperties()
    IMA_GetStatisticsProperties()
    IMA_GetPnpStatistics()
    IMA_GetIpProperties()
    IMA_SetIpConfigMethod()
    IMA_SetDefaultGateway()
    IMA_SetDnsServerAddress()
    IMA_SetSubnetMask()
  • Manage the Logical unit (LU) on HBAs and associated resources by calling:

    IMA_GetLuOid()
    IMA_GetLuOidList()
    IMA_GetLuProperties()
    IMA_LuInquiry()
    IMA_LuReadCapacity()
    IMA_LuReportLuns()
    IMA_ExposeLu()
    IMA_UnexposeLu()
  • Perform administrative operations on HBAs and associated resources by calling:

    IMA_GetAddressKeys()
    IMA_GetTargetOidList()
    IMA_GetTargetProperties()
    IMA_GetStatisticsProperties()
    IMA_GetTargetErrorStatistics()
    IMA_GetFirstBurstLengthProperties()
    IMA_SetFirstBurstLength()
    IMA_GetMaxBurstLengthProperties()
    IMA_SetMaxBurstLength()
    IMA_GetMaxRecvDataSegmentLengthPropertie()
    IMA_SetMaxRecvDataSegmentLength()
    IMA_GetMaxConnectionsProperties()
    IMA_SetMaxConnections()
    IMA_GetDefaultTime2RetainProperties()
    IMA_SetDefaultTime2Retain()
    IMA_GetDefaultTime2WaitProperties()
    IMA_SetDefaultTime2Wait()
    IMA_GetInitialR2TProperties()
    IMA_SetInitialRT2()
    IMA_GetMaxOutstandingRT2Properties()
    IMA_SetMaxOutstandingR2T()
    IMA_GetErrorRecoveryLevelProperties()
    IMA_SetErrorRecoveryLevel()
    IMA_GetImmediateDataProperties()
    IMA_SetImmediateData()
    IMA_GetDataPduInOrderProperties()
    IMA_SetDataPduInOrder()
    IMA_GetDataSequenceInOrderProperties()
    IMA_SetDataSequenceInOrder()
    IMA_GetDeviceStatistics()
    IMA_SetStatisti
    IMA_GetSessionOidList()
    IMA_GetDigestProperties()
    IMA_GetDigestValues()
    IMA_SetDataDigestValues()
    IMA_SetHeaderDigestValues()
    IMA_GetIFMarkerProperties()
    IMA_SetIFMarkerProperties()
    IMA_GetOFMarkerProperties()
    IMA_SetOFMarkerProperties()
    IMA_GetIFMarkIntProperties()
    IMA_SetIFMarkIntProperties()
    IMA_GetOFMarkIntProperties()
    IMA_SetOFMarkIntProperties()
    IMA_GetInitiatorLocalAuthParms()
    IMA_GetInUseInitiatorAuthMethods()IMA_SetInitiatorAuthMethods()
    IMA_GetInitiatorAuthParms()
    IMA_SetInitiatorAuthParms()
    IMA_SetInitiatorLocalAuthParms()
    IMA_GetIpsecProperties()
    IMA_RemoveStaleData()
    IMA_GetMutualLocalAuthParms()
    IMA_SetMutualLocalAuthParms()
    IMA_GetStatisticsProperties()
    IMA_GetDeviceStatistics()
    IMA_SetStatisticsCollection()
    IMA_GetObjectType()
    IMA_FreeMemory()
    IMA_RegisterForObjectVisibilityChanges()
    IMA_DeregisterForObjectVisibilityChanges()
    IMA_RegisterForObjectPropertyChanges()
    IMA_DeregisterForObjectPropertyChanges()
    SUN_IMA_SetTunableProperties()
    SUN_IMA_GetTunableProperties()
  • Physical HBAs and node specific APIs

    IMA_GetSharedNodeOid()
    IMA_GetNonSharedNodeOidList()
    IMA_GetNodeProperties()
    IMA_SetNodeName()
    IMA_GenerateNodeName()
    IMA_SetNodeAlias()
    IMA_GetAssociatedPluginOid()
    IMA_GetPhbaStatus()
    IMA_GetPhbaDownloadProperties()
    IMA_IsPhbaDownloadFile()
    IMA_PhbaDownload()
  • Library and plugin specific APIs

    IMA_GetLibraryProperties()
    IMA_GetPluginOidList()
    IMA_GetPluginProperties()
    IMA_PluginIOCtl()
    IMA_GetAssociatedPluginOid()

STATUS

STATUS is an enumerated type used to indicate the status of an API call. Most statuses are errors, however some are not. The non-error statuses indicate that an operation is successfully completed. However, there is an additional information that the client needs to be aware of and the status indicates what this information is.

Non-error Status:

IMA_STATUS_SUCCESS

This status indicates that the API call succeeded.

IMA_STATUS_REBOOT_NECESSARY

This status indicates that the operation is succeeded, but a reboot is necessary for the change to take affect.

IMA_STATUS_INCONSISTENT_NODE_PROPERTIES

This status indicates there is an inconsistency between the node properties, specifically either the node name or node alias, kept by the library and one or more plugins. The client should set both the node names using IMA_SetNodeName and the node alias using IMA_SetNodeAlias to fix this problem.

IMA_STATUS_SCSI_STATUS_CONDITION_MET

This status indicates that a SCSI command is succeeded with a CONDITION MET status.

Error Status:

IMA_ERROR_NOT_SUPPORTED

This error indicates that the specified API is not supported by the owner of the object.

IMA_ERROR_INSUFFICIENT_MEMORY

This error indicates that there was insufficient memory to complete the request. It is possible that any API can return this error.

IMA_ERROR_LAST_PRIMARY_DISCOVERY_METHOD

This error indicates that the call would disable the last primary discovery method for the PHBA specified in the call. A client is not allowed to disable all primary discovery methods for a PHBA.

IMA_ERROR_UNEXPECTED_OS_ERROR

This error indicates that either the library or the plugin encountered an unexpected error from an operating system API while attempting to perform the requested operation.

IMA_ERROR_SYNC_TIMEOUT

This error indicates that an attempt to acquire ownership of some synchronization mechanism, such as a mutex or semaphore, has timed out.

IMA_ERROR_LU_EXPOSED

This error indicates the requested operation cannot be completed because an LU is currently exposed to the operating system. For the called API to succeed the logical unit shall not be exposed to the operating system. This error is returned by the IMA_ExposeLu and IMA_RemoveStaticDiscoveryTarget APIs.

IMA_ERROR_LU_NOT_EXPOSED

This error indicates an attempt to use a logical unit that is not currently exposed to the operating system. For the called API to succeed the logical unit shall be exposed to the operating system. This error is returned by the IMA_UnexposeLu and the IMA_GetDeviceStatistics APIs.

IMA_ERROR_LU_IN_USE

This error indicates an attempt to unexpose a logical unit that is in use by the operating system. This error is returned by the IMA_UnexposeLu API.

IMA_ERROR_TARGET_TIMEOUT

This error indicates that communication with a target was necessary to perform the requested API and that the target did not respond to a command that was sent to it.

IMA_ERROR_STATS_COLLECTION_NOT_ENABLED

This error indicates that an attempt was made to retrieve statistics from an object that did not have statistics collection enabled.

IMA_ERROR_SCSI_STATUS_CHECK_CONDITION

This error indicates that a SCSI command failed with a CHECK CONDITION status.

IMA_ERROR_SCSI_STATUS_BUSY

This error indicates that a SCSI command failed with a BUSY status.

IMA_ERROR_SCSI_STATUS_RESERVATION_CONFLICT

This error indicates that a SCSI command failed with a RESERVATION CONFLICT status.

IMA_ERROR_SCSI_STATUS_TASK_SET_FULL

This error indicates that a SCSI command failed with a TASK SET FULL status.

IMA_ERROR_SCSI_STATUS_ACA_ACTIVE

This error indicates that a SCSI command failed with a ACA ACTIVE status.

IMA_ERROR_SCSI_STATUS_TASK_ABORTED

This error indicates that a SCSI command failed with a TASK ABORTED status.

IMA_ERROR_PLUGINS_NOT_SUPPORTED

This error indicates that the library implementation does not support plugins.

IMA_ERROR_INVALID_PARAMETER

This error indicates that a specified parameter was invalid.

This error can be returned in a number of situations, such as:

  1. When a client calls an API and specifies a NULL pointer as a parameter to an API that does not accept NULL pointers.

  2. When a client calls an API and specifies an integer parameter that is out range of the acceptable values for the parameter.

  3. When a client specifies a pointer to a structure as a parameter to an API and the contents of the structure contain invalid pointers or out of range integer parameters as stated above.

IMA_ERROR_INVALID_OBJECT_TYPE

This error indicates that the object type of the specified IMA_OID structure is invalid. Most likely an uninitialized variable or a corrupted variable was used in an API call.

IMA_ERROR_INCORRECT_OBJECT_TYPE

This error indicates that an object with an incorrect type was specified in an API call. This can be caused by passing an object ID of the wrong type to an API call. It can also be caused by using an uninitialized variable or a corrupted variable.

IMA_ERROR_OBJECT_NOT_FOUND

This error indicates an object specified in the API call was not found. This can be caused by using an uninitialized variable or a corrupted variable. It can also be caused by using an object ID that referred to an object or plugin that is no longer known to the system.

IMA_ERROR_NAME_TOO_LONG

This error indicates that a name specified in an API call is too long.

IMA_ERROR_UNKNOWN_ERROR

This error indicates that some sort of unknown error has occurred.

Files

/usr/lib/libima.so.1

Shared object

/usr/lib/64/libima.so.1

64-bit shared object

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Volatile
Availability
system/library/storage/snia-ima
MT-Level
Safe

See Also

intro(3), attributes(7), IMA_RemoveDiscoveryAddress(3IMA), IMA_GetDiscoveryAddressProperties(3IMA), IMA_RegisterForObjectVisibilityChanges(3IMA), IMA_GetDiscoveryProperties(3IMA)