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