Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/lib/libisns Initial import of libisns, contributed to the Ne...
details: https://anonhg.NetBSD.org/src/rev/7cc83a9cfe8f
branches: trunk
changeset: 760890:7cc83a9cfe8f
user: agc <agc%NetBSD.org@localhost>
date: Sun Jan 16 01:22:50 2011 +0000
description:
Initial import of libisns, contributed to the NetBSD Foundation by
Wasabi Systems, Inc.
libisns(3) is an implementation of the iSNS protocol as defined in
IETF RFC 4171, exporting an API that simplifies Internet Storage Name
Service (iSNS) client implementations.
diffstat:
lib/libisns/Makefile | 16 +
lib/libisns/isns.3 | 203 ++++++
lib/libisns/isns.c | 239 +++++++
lib/libisns/isns.h | 67 ++
lib/libisns/isns_config.h | 86 ++
lib/libisns/isns_defs.h | 197 ++++++
lib/libisns/isns_fileio.c | 76 ++
lib/libisns/isns_fileio.h | 47 +
lib/libisns/isns_pdu.c | 1334 +++++++++++++++++++++++++++++++++++++++++++
lib/libisns/isns_pdu.h | 222 +++++++
lib/libisns/isns_socketio.c | 102 +++
lib/libisns/isns_socketio.h | 56 +
lib/libisns/isns_task.c | 520 ++++++++++++++++
lib/libisns/isns_task.h | 97 +++
lib/libisns/isns_thread.c | 549 +++++++++++++++++
lib/libisns/isns_thread.h | 60 +
lib/libisns/isns_util.c | 286 +++++++++
lib/libisns/isns_util.h | 67 ++
lib/libisns/shlib_version | 5 +
19 files changed, 4229 insertions(+), 0 deletions(-)
diffs (truncated from 4305 to 300 lines):
diff -r c0d7464da3ce -r 7cc83a9cfe8f lib/libisns/Makefile
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libisns/Makefile Sun Jan 16 01:22:50 2011 +0000
@@ -0,0 +1,16 @@
+# $NetBSD: Makefile,v 1.1.1.1 2011/01/16 01:22:50 agc Exp $
+
+.include <bsd.own.mk>
+
+LIB= isns
+SRCS= isns.c isns_pdu.c isns_socketio.c isns_task.c isns_thread.c
+SRCS+= isns_util.c isns_fileio.c
+
+MAN= isns.3
+
+INCS= isns.h isns_defs.h
+INCSDIR=/usr/include
+
+WARNS= 4
+
+.include <bsd.lib.mk>
diff -r c0d7464da3ce -r 7cc83a9cfe8f lib/libisns/isns.3
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libisns/isns.3 Sun Jan 16 01:22:50 2011 +0000
@@ -0,0 +1,203 @@
+.\" $NetBSD: isns.3,v 1.1.1.1 2011/01/16 01:22:50 agc Exp $
+.\"
+.\" Copyright (c) 2004,2009 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Wasabi Systems, Inc.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\" notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\" notice, this list of conditions and the following disclaimer in the
+.\" documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.Dd October 1, 2009
+.Dt ISNS 3
+.Os
+.Sh NAME
+.Nm isns
+.Nd iSNS protocol support library
+.Sh LIBRARY
+.Lb libisns
+.Sh SYNOPSIS
+.In isns.h
+.Ft int
+.Fn isns_init "ISNS_HANDLE *h" "int is_server"
+.Ft void
+.Fn isns_stop "ISNS_HANDLE h"
+.Ft int
+.Fn isns_add_servercon "ISNS_HANDLE h" "int fd" "struct addrinfo *ai"
+.Ft int
+.Fn isns_init_reg_refresh "ISNS_HANDLE h" "const char *node" "int interval"
+.Ft ISNS_TRANS
+.Fn isns_new_trans "ISNS_HANDLE h" "uint16_t func_id" "uint16_t pdu_flags"
+.Ft int
+.Fn isns_add_tlv "ISNS_TRANS t" "uint32_t tag" "int data_len" "const void *data_p"
+.Ft int
+.Fn isns_add_string "ISNS_TRANS t" "uint32_t tag" "const char *s"
+.Ft int
+.Fn isns_send_trans "ISNS_TRANS t" "const struct timespec *timeout_p" "uint32_t *status_p"
+.Ft int
+.Fn isns_get_tlv "ISNS_TRANS t" "int which_tlv" "uint32_t *tag_p" "int data_len_p" "void **data_pp"
+.Ft void
+.Fn isns_free_trans "ISNS_TRANS t"
+.Sh DESCRIPTION
+The
+.Nm
+library exports an API that simplifies Internet Storage Name
+Service (iSNS) client implementations.
+The API defines a transactional model in support of:
+.Pp
+.Bl -bullet -width 3n -offset indent -compact
+.It
+generating iSNS messages composed of iSNS attributes expressed in
+Tag-Length-Value (TLV) data format
+.It
+submitting iSNS Protocol (iSNSP) messages
+.It
+optionally waiting for iSNSP responses
+.El
+.Pp
+.Nm
+does not currently support receipt of iSNS Heartbeat messages, State Change
+Notification (SCN) messages, or Entity Status Inquiry (ESI) messages.
+.Sh INITILAIZATION
+An iSNS client that uses
+.Nm
+must call
+.Fn 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).
+.Pp
+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
+.Fn isns_add_servercon ,
+.Fn isns_init_reg_refresh ,
+.Fn isns_stop ,
+and
+.Fn isns_new_trans .
+.Pp
+.Fn isns_stop
+should be called when the iSNS environment is no longer needed.
+This call will kill any threads created by
+.Fn isns_init .
+.Sh CONFIGURATION
+Following initialization,
+.Fn 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.
+.Pp
+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
+.Nm
+in the event that the TCP connection is broken.
+.Pp
+Certain iSNS servers will limit registration lifetimes, and will
+refresh registrations after any request from a given iSNS entity.
+The
+.Fn isns_init_reg_refresh
+function offers a way for
+.Nm
+to refresh registrations on behalf of the iSNS client.
+.Pp
+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'.
+.Sh TRANSACTIONS
+.Fn isns_new_trans
+creates new iSNS transactions.
+.Pp
+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'.
+.Pp
+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
+.Fn isns_add_tlv
+or
+.Fn isns_add_string .
+.Pp
+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.
+.Fn isns_add_string
+may be used if the attribute value is a NUL terminated C string.
+.Pp
+Once a transaction has been populated with any required TLV data,
+.Fn isns_send_trans
+can be used to submit an iSNSP registration or query message.
+.Pp
+Callers that submit iSNSP query messages may need to wait for returned data.
+.Fn 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.
+.Pp
+.Fn isns_get_tlv
+is used to retrieve TLV data returned in a transaction.
+The first call to
+.Fn 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.
+.Pp
+When a caller is done with a transaction, having submitted either a
+registration or a query message and retrieved any returned TLV data,
+.Fn isns_free_trans()
+should be used to release resources used by the transaction.
+.Sh RETURN VALUES
+.Fn isns_init ,
+.Fn isns_add_servercon ,
+.Fn isns_init_reg_refresh ,
+.Fn isns_add_tlv ,
+.Fn isns_add_string ,
+and
+.Fn isns_send_trans
+return 0 on success, or -1 on failure.
+.Fn isns_new_trans
+returns 0 on success, or ISNS_INVALID_TRANS on failure.
+.Fn isns_get_tlv
+returns 0 on success, or ENOENT if there are no TLVs yo retrieve.
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 6.0 .
+The
+.Nm
+implementation was contributed to the NetBSD Foundation
+by Wasabi Systems, Inc.
diff -r c0d7464da3ce -r 7cc83a9cfe8f lib/libisns/isns.c
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libisns/isns.c Sun Jan 16 01:22:50 2011 +0000
@@ -0,0 +1,239 @@
+/* $NetBSD: isns.c,v 1.1.1.1 2011/01/16 01:22:50 agc Exp $ */
+
+/*-
+ * Copyright (c) 2004,2009 The NetBSD Foundation, Inc.
+ * All rights reserved.
+ *
+ * This code is derived from software contributed to The NetBSD Foundation
+ * by Wasabi Systems, Inc.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * 1. Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+ * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+ * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+ * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#include <sys/cdefs.h>
+__RCSID("$NetBSD: isns.c,v 1.1.1.1 2011/01/16 01:22:50 agc Exp $");
+
+/*
+ * isns.c
+ */
+
+#include <sys/types.h>
+#include <sys/param.h>
+#include <sys/uio.h>
+#include <sys/poll.h>
+
+#include <errno.h>
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+
+#include "isns.h"
+#include "isns_config.h"
+
+
+
+/*
+ * isns_init()
+ */
+int
+isns_init(ISNS_HANDLE *isns_handle_p, int is_server)
+{
+ struct isns_config_s *cfg_p;
+ int rval;
+
+ *isns_handle_p = NULL;
+
+ if ((cfg_p = isns_new_config()) == NULL) {
+ DBG("isns_init: error on isns_new_config()\n");
+ return ENOMEM;
+ }
+
Home |
Main Index |
Thread Index |
Old Index