unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-6.1.5)
Page:
Section:
Apropos / Subsearch:
optional field

ISNS(3)                    Library Functions Manual                    ISNS(3)

NAME
     isns -- iSNS protocol support library

LIBRARY
     Internet Storage Name Service Library (libisns, -lisns)

SYNOPSIS
     #include <&lt;isns.h>&gt;

     int
     isns_init(ISNS_HANDLE *h, int is_server);

     void
     isns_stop(ISNS_HANDLE h);

     int
     isns_add_servercon(ISNS_HANDLE h, int fd, struct addrinfo *ai);

     int
     isns_init_reg_refresh(ISNS_HANDLE h, const char *node, int interval);

     ISNS_TRANS
     isns_new_trans(ISNS_HANDLE h, uint16_t func_id, uint16_t pdu_flags);

     int
     isns_add_tlv(ISNS_TRANS t, uint32_t tag, int data_len, const void
     *data_p);

     int
     isns_add_string(ISNS_TRANS t, uint32_t tag, const char *s);

     int
     isns_send_trans(ISNS_TRANS t, const struct timespec *timeout_p, uint32_t
     *status_p);

     int
     isns_get_tlv(ISNS_TRANS t, int which_tlv, uint32_t *tag_p, int
     data_len_p, void **data_pp);

     void
     isns_free_trans(ISNS_TRANS t);

DESCRIPTION
     The isns library exports an API that simplifies Internet Storage Name
     Service (iSNS) client implementations.  The API defines a transactional
     model in support of:

           o    generating iSNS messages composed of iSNS attributes expressed
                in Tag-Length-Value (TLV) data format
           o    submitting iSNS Protocol (iSNSP) messages
           o    optionally waiting for iSNSP responses

     isns does not currently support receipt of iSNS Heartbeat messages, State
     Change Notification (SCN) messages, or Entity Status Inquiry (ESI)
     messages.

INITIALIZATION
     An iSNS client that uses isns must call isns_init() to initialize the
     iSNS environment.  This call will create a thread to handle client-server
     communication, and as such should only be called when thread creation is
     appropriate (such as after a daemonized program forks).

     The value passed as is_server is used to set iSNSP message format Flags
     "Sender is the iSNS client" (bit position 16) and "Sender is the iSNS
     server" (bit position 17).  For now the value 0 (zero) should be passed
     for is_server.  The value returned in h should be considered opaque by
     the caller.  This value is passed unchanged to isns_add_servercon(),
     isns_init_reg_refresh(), isns_stop(), and isns_new_trans().

     isns_stop() should be called when the iSNS environment is no longer
     needed.  This call will kill any threads created by isns_init().

CONFIGURATION
     Following initialization, isns_add_servercon() should be used to make the
     iSNS environment aware of the iSNS server to which iSNSP queries and
     requests are to be sent.  This routine should not be called by a program
     acting as an iSNS server.

     A connected TCP socket descriptor is passed as parameter fd.  Parameter
     ai is the address of the remote TCP endpoint.  It is included so that
     reconnection may be attempted by isns in the event that the TCP
     connection is broken.

     Certain iSNS servers will limit registration lifetimes, and will refresh
     registrations after any request from a given iSNS entity.  The
     isns_init_reg_refresh() function offers a way for isns to refresh
     registrations on behalf of the iSNS client.

     Parameter node is the ``iSCSI Name'' attribute used for the periodic
     queries.  It should be the name of an iSCSI node within the registered
     iSNS entity.  The desired refresh interval, in seconds, is passed in
     parameter interval.

TRANSACTIONS
     isns_new_trans() creates new iSNS transactions.

     Parameter func_id is used as the iSNSP message id.  Parameter pdu_flags
     is used to set iSNSP message format Flags and is exposed to allow callers
     to set flag "Replace flag" (bit position 19).  This provides callers with
     a way to specify whether a Device Attribute Registration Request is
     intended to update or replace an existing registration.  This is
     currently the only use defined for parameter pdu_flags.

     Once a new transaction has been created, callers can specify iSNS
     attributes used for registration and query requests.  TLV data may be
     added using either isns_add_tlv() or isns_add_string().

     Parameter tag is the iSNS Tag corresponding to the attribute being added.
     Parameter data_len is the length of the attribute value.  Parameter
     data_p references the attribute value.  The caller does not need to
     handle iSNS attribute 4-byte alignment requirements.  This is handled by
     the iSNS environment on behalf of the caller.  isns_add_string() may be
     used if the attribute value is a NUL terminated C string.

     Once a transaction has been populated with any required TLV data,
     isns_send_trans() can be used to submit an iSNSP registration or query
     message.

     Callers that submit iSNSP query messages may need to wait for returned
     data.  isns_send_trans() supports bounded waits.  Successful waits, those
     that do not time out, return the iSNSP response status code received in
     the iSNSP response message.  If a wait does time out, the value of
     status_p is undefined.  Callers that do not need to wait for returned
     data can simply pass NULL for parameter timeout_p.  Callers should set
     parameter status_p to NULL if not waiting.

     isns_get_tlv() is used to retrieve TLV data returned in a transaction.
     The first call to isns_get_tlv() should pass the value ISNS_TLV_FIRST for
     parameter which_tlv.  Each subsequent TLV can be retrieved by passing in
     ISNS_TLV_NEXT in place of ISNS_TLV_FIRST.

     When a caller is done with a transaction, having submitted either a
     registration or a query message and retrieved any returned TLV data,
     isns_free_trans() should be used to release resources used by the
     transaction.

RETURN VALUES
     isns_init(), isns_add_servercon(), isns_init_reg_refresh(),
     isns_add_tlv(), isns_add_string(), and isns_send_trans() return 0 on
     success, or -1 on failure.  isns_new_trans() returns 0 on success, or
     ISNS_INVALID_TRANS on failure.  isns_get_tlv() returns 0 on success, or
     ENOENT if there are no TLVs to retrieve.

HISTORY
     isns first appeared in NetBSD 6.0.  The isns implementation was
     contributed to the NetBSD Foundation by Wasabi Systems, Inc.

NetBSD 6.1.5                    October 1, 2009                   NetBSD 6.1.5