Tribblix: manual page: scsi_wwnstr_to

SCSI_WWNSTR_TO_WWN(9F) Kernel Functions for Drivers SCSI_WWNSTR_TO_WWN(9F)

NAME

scsi_wwnstr_to_wwn, scsi_wwn_to_wwnstr, scsi_free_wwnstr - SCSI World
Wide Name string conversion functions

SYNOPSIS

#include <sys/scsi/scsi.h>

int
scsi_wwnstr_to_wwn(const char *wwwnstr, uint64_t *wwnp);

char *
scsi_wwn_to_wwnstr(uint64_t wwn, int ua_form, char *wwnstr);

void
scsi_free_wwnstr(char *wwnstr);

INTERFACE LEVEL

Evolving - This interface is still evolving in illumos. API and ABI
stability is not guaranteed.

PARAMETERS

wwn A 64-bit world wide number.

wwnstr A string representation of a world wide number.

wwnp A pointer to a 64-bit value that will store a world wide
number.

ua_form An integer indicating whether or not the unit address
form should be used.

DESCRIPTION

The scsi_wwnstr_to_wwn() and scsi_wwn_to_wwnstr() functions convert an
8-byte world wide number to and from a string representation.

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.

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 `w' character. When this is present, this is
called the 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:

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.

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.

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.

The scsi_wwnstr_to_wwn() function parses the string form of the WWN
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 wwnp.

The scsi_wwn_to_wwnstr() converts the world wide number in wwn into a
human-readable string as described above. If the ua_form is non-zero
then the unit-address form is used and a leading `w' is placed.

If the 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 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.

If the wwnstr argument is instead 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
scsi_free_wwnstr() function.

CONTEXT

The scsi_wwnstr_to_wwn(), scsi_wwn_to_wwnstr(), and scsi_free_wwnstr()
functions may be used in user, kernel, and interrupt context.

RETURN VALUES

Upon successful completion, the scsi_wwnstr_to_wwn() function returns
DDI_SUCCESS and fills in wwnp with the WWN. Otherwise, DDI_FAILURE is
returned, indicating an invalid argument or a malformed string in
wwnstr.

Upon successful completion, the scsi_wwn_to_wwnstr() function returns a
pointer to the start of the world wide number. Otherwise NULL is
returned to indicate that the conversion failed.