share/man/man9f/scsi_wwnstr_to_wwn.9f

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright (c) 2017, Joyent, Inc.
  13 .\"
  14 .Dd Feb 28, 2017
  15 .Dt SCSI_WWNSTR_TO_WWN 9F
  16 .Os
  17 .Sh NAME
  18 .Nm scsi_wwnstr_to_wwn ,
  19 .Nm scsi_wwn_to_wwnstr ,
  20 .Nm scsi_free_wwnstr
  21 .Nd SCSI World Wide Name string conversion functions
  22 .Sh SYNOPSIS
  23 .In sys/scsi/scsi.h
  24 .Ft int
  25 .Fo scsi_wwnstr_to_wwn
  26 .Fa "const char *wwwnstr"
  27 .Fa "uint64_t *wwnp"
  28 .Fc
  29 .Ft "char *"
  30 .Fo scsi_wwn_to_wwnstr
  31 .Fa "uint64_t wwn"
  32 .Fa "int ua_form"
  33 .Fa "char *wwnstr"
  34 .Fc
  35 .Ft void
  36 .Fo scsi_free_wwnstr
  37 .Fa "char *wwnstr"
  38 .Fc
  39 .Sh INTERFACE LEVEL
  40 .Sy Evolving -
  41 This interface is still evolving in illumos.
  42 API and ABI stability is not guaranteed.
  43 .Sh PARAMETERS
  44 .Bl -tag -width Fa
  45 .It Fa wwn
  46 A 64-bit world wide number.
  47 .It Fa wwnstr
  48 A string representation of a world wide number.
  49 .It Fa wwnp
  50 A pointer to a 64-bit value that will store a world wide number.
  51 .It Fa ua_form
  52 An integer indicating whether or not the unit address form should be
  53 used.
  54 .El
  55 .Sh DESCRIPTION
  56 The
  57 .Fn scsi_wwnstr_to_wwn
  58 and
  59 .Fn scsi_wwn_to_wwnstr
  60 functions convert an 8-byte world wide number to and from a string
  61 representation.
  62 .Pp
  63 World wide numbers are unique identifiers that are used in storage
  64 technologies, particularly ATA, SAS, and FC.
  65 The format of a WWN is defined by the IEEE and generally come in 8 and
  66 16 byte forms.
  67 These interfaces only operate on the 8 byte forms.
  68 .Pp
  69 When the WWN is represented as a string, it is represented as a 16
  70 character hexadecimal string.
  71 This character string may either use uppercase or lowercase hexadecimal
  72 characters.
  73 The character string may be preceded by a
  74 .Sq w
  75 character.
  76 When this is present, this is called the
  77 .Em unit-address form .
  78 If the string is not 16 ASCII character long or 17, when using the
  79 unit-address form, the string is considered invalid.
  80 The following macros are provided to help deal with these lengths:
  81 .Bl -tag -width Dv
  82 .It Dv SCSI_WWN_STRLEN
  83 The number of bytes, excluding a terminating nul character, for a world
  84 wide number to be represented when not in the unit-address form.
  85 .It Dv SCSI_WWN_UA_STRLEN
  86 The number of bytes, excluding a terminating nul character, for a world
  87 wide number to be represented in the unit-address form.
  88 .It Dv SCSI_WWN_BUFLEN
  89 A number of bytes that is guaranteed to be sufficient to hold any form
  90 of a world wide number and a nul terminator.
  91 .El
  92 .Pp
  93 The
  94 .Fn scsi_wwnstr_to_wwn
  95 function parses the string form of the WWN
  96 .Fa wwnstr
  97 and converts it to a 64-bit representation.
  98 The string form may either be in unit-address form or not.
  99 The string must have a nul terminator.
 100 If the string is successfully parsed, the world wide number is stored in
 101 .Fa wwnp .
 102 .Pp
 103 The
 104 .Fn scsi_wwn_to_wwnstr
 105 converts the world wide number in
 106 .Fa wwn
 107 into a human-readable string as described above.
 108 If the
 109 .Fa ua_form
 110 is non-zero then the unit-address form is used and a leading
 111 .Sq w
 112 is placed.
 113 .Pp
 114 If the
 115 .Fa wwnstr
 116 argument is supplied by the user, then it must be large enough to
 117 contain both the string form of the world wide number and a nul
 118 character.
 119 The
 120 .Dv SCSI_WWN_BUFLEN
 121 macro is recommended.
 122 It will always ensure that a buffer is large
 123 enough to hold any supported string representation of a world wide
 124 number.
 125 .Pp
 126 If the
 127 .Fa wwnstr
 128 argument is instead
 129 .Dv NULL ,
 130 then a character string of sufficient size will be allocated by the
 131 system.
 132 Note, this allocation will block until memory is available.
 133 If memory is allocated in this way, then the caller should free this
 134 memory with the
 135 .Fn scsi_free_wwnstr
 136 function.
 137 .Sh CONTEXT
 138 The
 139 .Fn scsi_wwnstr_to_wwn ,
 140 .Fn scsi_wwn_to_wwnstr ,
 141 and
 142 .Fn scsi_free_wwnstr
 143 functions may be used in
 144 .Sy user ,
 145 .Sy kernel ,
 146 and
 147 .Sy interrupt
 148 context.
 149 .Sh RETURN VALUES
 150 Upon successful completion, the
 151 .Fn scsi_wwnstr_to_wwn
 152 function returns
 153 .Dv DDI_SUCCESS
 154 and fills in
 155 .Fa wwnp
 156 with the WWN.
 157 Otherwise,
 158 .Dv DDI_FAILURE
 159 is returned, indicating an invalid argument or a malformed string in
 160 .Fa wwnstr .
 161 .Pp
 162 Upon successful completion, the
 163 .Fn scsi_wwn_to_wwnstr
 164 function returns a pointer to the start of the world wide number.
 165 Otherwise
 166 .Dv NULL
 167 is returned to indicate that the conversion failed.
 168 .Sh SEE ALSO
 169 .Xr scsi_hba_iport_unit_address 9F