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 - 41This interface is still evolving in illumos. 42API and ABI stability is not guaranteed. 43.Sh PARAMETERS 44.Bl -tag -width Fa 45.It Fa wwn 46A 64-bit world wide number. 47.It Fa wwnstr 48A string representation of a world wide number. 49.It Fa wwnp 50A pointer to a 64-bit value that will store a world wide number. 51.It Fa ua_form 52An integer indicating whether or not the unit address form should be 53used. 54.El 55.Sh DESCRIPTION 56The 57.Fn scsi_wwnstr_to_wwn 58and 59.Fn scsi_wwn_to_wwnstr 60functions convert an 8-byte world wide number to and from a string 61representation. 62.Pp 63World wide numbers are unique identifiers that are used in storage 64technologies, particularly ATA, SAS, and FC. 65The format of a WWN is defined by the IEEE and generally come in 8 and 6616 byte forms. 67These interfaces only operate on the 8 byte forms. 68.Pp 69When the WWN is represented as a string, it is represented as a 16 70character hexadecimal string. 71This character string may either use uppercase or lowercase hexadecimal 72characters. 73The character string may be preceded by a 74.Sq w 75character. 76When this is present, this is called the 77.Em unit-address form . 78If the string is not 16 ASCII character long or 17, when using the 79unit-address form, the string is considered invalid. 80The following macros are provided to help deal with these lengths: 81.Bl -tag -width Dv 82.It Dv SCSI_WWN_STRLEN 83The number of bytes, excluding a terminating nul character, for a world 84wide number to be represented when not in the unit-address form. 85.It Dv SCSI_WWN_UA_STRLEN 86The number of bytes, excluding a terminating nul character, for a world 87wide number to be represented in the unit-address form. 88.It Dv SCSI_WWN_BUFLEN 89A number of bytes that is guaranteed to be sufficient to hold any form 90of a world wide number and a nul terminator. 91.El 92.Pp 93The 94.Fn scsi_wwnstr_to_wwn 95function parses the string form of the WWN 96.Fa wwnstr 97and converts it to a 64-bit representation. 98The string form may either be in unit-address form or not. 99The string must have a nul terminator. 100If the string is successfully parsed, the world wide number is stored in 101.Fa wwnp . 102.Pp 103The 104.Fn scsi_wwn_to_wwnstr 105converts the world wide number in 106.Fa wwn 107into a human-readable string as described above. 108If the 109.Fa ua_form 110is non-zero then the unit-address form is used and a leading 111.Sq w 112is placed. 113.Pp 114If the 115.Fa wwnstr 116argument is supplied by the user, then it must be large enough to 117contain both the string form of the world wide number and a nul 118character. 119The 120.Dv SCSI_WWN_BUFLEN 121macro is recommended. 122It will always ensure that a buffer is large 123enough to hold any supported string representation of a world wide 124number. 125.Pp 126If the 127.Fa wwnstr 128argument is instead 129.Dv NULL , 130then a character string of sufficient size will be allocated by the 131system. 132Note, this allocation will block until memory is available. 133If memory is allocated in this way, then the caller should free this 134memory with the 135.Fn scsi_free_wwnstr 136function. 137.Sh CONTEXT 138The 139.Fn scsi_wwnstr_to_wwn , 140.Fn scsi_wwn_to_wwnstr , 141and 142.Fn scsi_free_wwnstr 143functions may be used in 144.Sy user , 145.Sy kernel , 146and 147.Sy interrupt 148context. 149.Sh RETURN VALUES 150Upon successful completion, the 151.Fn scsi_wwnstr_to_wwn 152function returns 153.Dv DDI_SUCCESS 154and fills in 155.Fa wwnp 156with the WWN. 157Otherwise, 158.Dv DDI_FAILURE 159is returned, indicating an invalid argument or a malformed string in 160.Fa wwnstr . 161.Pp 162Upon successful completion, the 163.Fn scsi_wwn_to_wwnstr 164function returns a pointer to the start of the world wide number. 165Otherwise 166.Dv NULL 167is returned to indicate that the conversion failed. 168.Sh SEE ALSO 169.Xr scsi_hba_iport_unit_address 9F 170