.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright (c) 2017, Joyent, Inc.
.\"
.Dd Feb 28, 2017
.Dt SCSI_WWNSTR_TO_WWN 9F
.Os
.Sh NAME
.Nm scsi_wwnstr_to_wwn ,
.Nm scsi_wwn_to_wwnstr ,
.Nm scsi_free_wwnstr
.Nd SCSI World Wide Name string conversion functions
.Sh SYNOPSIS
.In sys/scsi/scsi.h
.Ft int
.Fo scsi_wwnstr_to_wwn
.Fa "const char *wwwnstr"
.Fa "uint64_t *wwnp"
.Fc
.Ft "char *"
.Fo scsi_wwn_to_wwnstr
.Fa "uint64_t wwn"
.Fa "int ua_form"
.Fa "char *wwnstr"
.Fc
.Ft void
.Fo scsi_free_wwnstr
.Fa "char *wwnstr"
.Fc
.Sh INTERFACE LEVEL
.Sy Evolving -
This interface is still evolving in illumos.
API and ABI stability is not guaranteed.
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa wwn
A 64-bit world wide number.
.It Fa wwnstr
A string representation of a world wide number.
.It Fa wwnp
A pointer to a 64-bit value that will store a world wide number.
.It Fa ua_form
An integer indicating whether or not the unit address form should be
used.
.El
.Sh DESCRIPTION
The
.Fn scsi_wwnstr_to_wwn
and
.Fn scsi_wwn_to_wwnstr
functions convert an 8-byte world wide number to and from a string
representation.
.Pp
World wide numbers are unique identifiers that are used in storage
technologies, particularly ATA, SAS, and FC.
The format of a WWN is defined by the IEEE and generally come in 8 and
16 byte forms.
These interfaces only operate on the 8 byte forms.
.Pp
When the WWN is represented as a string, it is represented as a 16
character hexadecimal string.
This character string may either use uppercase or lowercase hexadecimal
characters.
The character string may be preceded by a
.Sq w
character.
When this is present, this is called the
.Em unit-address form .
If the string is not 16 ASCII character long or 17, when using the
unit-address form, the string is considered invalid.
The following macros are provided to help deal with these lengths:
.Bl -tag -width Dv
.It Dv SCSI_WWN_STRLEN
The number of bytes, excluding a terminating nul character, for a world
wide number to be represented when not in the unit-address form.
.It Dv SCSI_WWN_UA_STRLEN
The number of bytes, excluding a terminating nul character, for a world
wide number to be represented in the unit-address form.
.It Dv SCSI_WWN_BUFLEN
A number of bytes that is guaranteed to be sufficient to hold any form
of a world wide number and a nul terminator.
.El
.Pp
The
.Fn scsi_wwnstr_to_wwn
function parses the string form of the WWN
.Fa wwnstr
and converts it to a 64-bit representation.
The string form may either be in unit-address form or not.
The string must have a nul terminator.
If the string is successfully parsed, the world wide number is stored in
.Fa wwnp .
.Pp
The
.Fn scsi_wwn_to_wwnstr
converts the world wide number in
.Fa wwn
into a human-readable string as described above.
If the
.Fa ua_form
is non-zero then the unit-address form is used and a leading
.Sq w
is placed.
.Pp
If the
.Fa wwnstr
argument is supplied by the user, then it must be large enough to
contain both the string form of the world wide number and a nul
character.
The
.Dv SCSI_WWN_BUFLEN
macro is recommended.
It will always ensure that a buffer is large
enough to hold any supported string representation of a world wide
number.
.Pp
If the
.Fa wwnstr
argument is instead
.Dv NULL ,
then a character string of sufficient size will be allocated by the
system.
Note, this allocation will block until memory is available.
If memory is allocated in this way, then the caller should free this
memory with the
.Fn scsi_free_wwnstr
function.
.Sh CONTEXT
The
.Fn scsi_wwnstr_to_wwn ,
.Fn scsi_wwn_to_wwnstr ,
and
.Fn scsi_free_wwnstr
functions may be used in
.Sy user ,
.Sy kernel ,
and
.Sy interrupt
context.
.Sh RETURN VALUES
Upon successful completion, the
.Fn scsi_wwnstr_to_wwn
function returns
.Dv DDI_SUCCESS
and fills in
.Fa wwnp
with the WWN.
Otherwise,
.Dv DDI_FAILURE
is returned, indicating an invalid argument or a malformed string in
.Fa wwnstr .
.Pp
Upon successful completion, the
.Fn scsi_wwn_to_wwnstr
function returns a pointer to the start of the world wide number.
Otherwise
.Dv NULL
is returned to indicate that the conversion failed.
.Sh SEE ALSO
.Xr scsi_hba_iport_unit_address 9F