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

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

#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);

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

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.

The () 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 . 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:

The number of bytes, excluding a terminating nul character, for a world wide number to be represented when not in the unit-address form.
The number of bytes, excluding a terminating nul character, for a world wide number to be represented in the unit-address form.
A number of bytes that is guaranteed to be sufficient to hold any form of a world wide number and a nul terminator.

The () 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 () 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 () function.

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

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.

scsi_hba_iport_unit_address(9F)

February 28, 2017 OmniOS