'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.TH HBA_GetAdapterName 3HBAAPI "1 Sep 2003" "SunOS 5.11" "Common Fibre Channel HBA Information Library Functions"
.SH NAME
HBA_GetAdapterName \- retrieve the name of a specific HBA
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-lHBAAPI\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <hbaapi.h>

\fBHBA_STATUS\fR \fBHBA_GetAdapterName\fR(\fBHBA_UINT32\fR \fIadapterindex\fR,
     \fBchar *\fR\fIadaptername\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIadapterindex\fR\fR
.ad
.RS 16n
.rt  
the index of the adapter, between 0 and one less than the value returned by \fBHBA_GetNumberOfAdapters\fR(3HBAAPI).
.RE

.sp
.ne 2
.mk
.na
\fB\fIadaptername\fR\fR
.ad
.RS 16n
.rt  
the buffer where the name of the adapter will be stored. The recommended size is 256 bytes.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBHBA_GetAdapterName()\fR function stores the name of the adapter specified by \fIadapterindex\fR in the buffer pointed to by \fIadaptername\fR.  The caller is responsible for allocating space for the name. 
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBHBA_STATUS_OK\fR is returned. Otherwise, an error value is returned and the content of \fIadaptername\fR is undefined.
.SH ERRORS
.sp
.LP
See \fBlibhbaapi\fR(3LIB) for general error status values.
.SH EXAMPLES
.LP
\fBExample 1 \fRReturn adapter name.
.sp
.LP
Given an \fIhbacount\fR >= 0 and < total number of adapters on the system, the following example returns the \fIadaptername\fR for that adapter.

.sp
.in +2
.nf
if ((status = HBA_GetAdapterName(hbaCount, adaptername)) !=
            HBA_STATUS_OK) {
        fprintf(stderr, "HBA %d name not available for "
            "reason %d\en", hbaCount, status);
        continue;
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5)  for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
T{
Standard: FC-HBA Version 4 (API version 2)
T}
_
MT-LevelSafe
_
StandardFC-MI 1.92 (API version 1)
.TE

.SH SEE ALSO
.sp
.LP
 \fBHBA_GetNumberOfAdapters\fR(3HBAAPI), \fBlibhbaapi\fR(3LIB), \fBattributes\fR(5)
.sp
.LP
T11 FC-MI Specification
.SH BUGS
.sp
.LP
The \fBHBA_GetAdapterName()\fR function does not take a name length argument to define how large the buffer is, yet the specification does not indicate a maximum name length.  Failure to pass in a large enough buffer will result in a buffer over-run, which may lead to segmentation faults or other failures.  Callers should be sure to allocate a large buffer to ensure the Vendor library will not overrun during the copy.