external/bsd/iscsi/dist/src/lib/libiscsi.3

   1 .\" $NetBSD: libiscsi.3,v 1.2 2009/06/30 02:44:52 agc Exp $
   2 .\"
   3 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This manual page is derived from software contributed to The
   7 .\" NetBSD Foundation by Alistair Crooks (agc@NetBSD.org)
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd June 24, 2009
  31 .Dt LIBISCSI 3
  32 .Os
  33 .Sh NAME
  34 .Nm libiscsi
  35 .Nd iSCSI network storage protocol implementation
  36 .Sh LIBRARY
  37 .Lb libiscsi
  38 .Sh SYNOPSIS
  39 .In iscsi.h
  40 .Ft int
  41 .Fo iscsi_target_set_defaults
  42 .Fa "iscsi_target_t *target"
  43 .Fc
  44 .Ft int
  45 .Fo iscsi_target_start
  46 .Fa "iscsi_target_t *target"
  47 .Fc
  48 .Ft int
  49 .Fo iscsi_target_listen
  50 .Fa "iscsi_target_t *target"
  51 .Fc
  52 .Ft int
  53 .Fo iscsi_target_shutdown
  54 .Fa "iscsi_target_t *target"
  55 .Fc
  56 .Ft void
  57 .Fo iscsi_target_write_pidfile
  58 .Fa "const char *filename"
  59 .Fc
  60 .Ft int
  61 .Fo iscsi_target_setvar
  62 .Fa "iscsi_target_t *target" "const char *name" "const char *value"
  63 .Fc
  64 .Ft char *
  65 .Fo iscsi_target_getvar
  66 .Fa "iscsi_target_t *target" "const char *name"
  67 .Fa "iscsi_target_t *target"
  68 .Fc
  69 .Ft int
  70 .Fo iscsi_initiator_set_defaults
  71 .Fa "iscsi_initiator_t *initiator"
  72 .Fc
  73 .Ft int
  74 .Fo iscsi_initiator_start
  75 .Fa "iscsi_initiator_t *initiator"
  76 .Fc
  77 .Ft int
  78 .Fo iscsi_initiator_discover
  79 .Fa "iscsi_initiator_t *initiator" "char *x" "uint64_t a" "int b"
  80 .Fc
  81 .Ft int
  82 .Fo iscsi_initiator_shutdown
  83 .Fa "iscsi_initiator_t *initiator"
  84 .Fc
  85 .Ft int
  86 .Fo iscsi_initiator_setvar
  87 .Fa "iscsi_initiator_t *initiator" "const char *name" "const char *value"
  88 .Fc
  89 .Ft char *
  90 .Fo iscsi_initiator_getvar
  91 .Fa "iscsi_initiator_t *initiator" "const char *name"
  92 .Fc
  93 .Sh DESCRIPTION
  94 .Nm
  95 is a library interface to the iSCSI target and initiator.
  96 This conforms to IETF RFC 3720.
  97 The corresponding command line utilities for
  98 .Nm
  99 are
 100 .Xr iscsi-initiator 8
 101 and
 102 .Xr iscsi-target 8 .
 103 .Pp
 104 In normal operation, a process acting as
 105 a target (i.e. presenting storage to the network)
 106 will call
 107 .Fn iscsi_target_set_defaults
 108 and will then set various values using the
 109 .Fn iscsi_target_setvar
 110 function.
 111 The value of a variable can be retrieved
 112 at any time using the
 113 .Fn iscsi_target_getvar
 114 function.
 115 When all of the variables have been set,
 116 the
 117 .Fn iscsi_target_start
 118 function is called, and the block storage will be
 119 served up by the process.
 120 .Pp
 121 A useful illustration of the use of these functions
 122 can be found in the source code to the
 123 .Xr iscsi-target 8
 124 utility.
 125 .Pp
 126 The
 127 .Nm
 128 library also provides an implementation of the client
 129 end of the iSCSI subsystem, which is known as the
 130 initiator.
 131 The process acting as an initiator will first call the
 132 .Fn iscsi_initiator_set_defaults
 133 function, to set default values for the initiator variables.
 134 Once all the values have been set to the user preferences
 135 using the
 136 .Fn iscsi_initiator_setvar
 137 function, then the
 138 .Fn iscsi_initiator_start
 139 function is called.
 140 .Pp
 141 The
 142 .Nm
 143 library can be used to perform iSCSI device discovery
 144 by calling the
 145 .Fn iscsi_initiator_discovery
 146 function.
 147 This will return a list of all the iSCSI targets which
 148 are serving up block storage according to the variables
 149 which have already been set.
 150 .Sh SEE ALSO
 151 .Xr iscsi-initiator 8
 152 .Xr iscsi-target 8
 153 .Sh HISTORY
 154 The
 155 .Nm
 156 library first appeared in
 157 .Nx 4.0 .
 158 This programmatic interface to the
 159 .Nm library first appeared in
 160 .Nx 6.0 .
 161 .Sh AUTHOR
 162 .An Alistair Crooks Aq agc@NetBSD.org .