'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DI_DEVFS_PATH 3DEVINFO "May 15, 2008"
.SH NAME
di_devfs_path, di_devfs_minor_path, di_path_devfs_path,
di_path_client_devfs_path, di_devfs_path_free \- generate and free path names
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
#include <libdevinfo.h>

\fBchar *\fR\fBdi_devfs_path\fR(\fBdi_node_t\fR \fInode\fR);
.fi

.LP
.nf
\fBchar *\fR\fBdi_devfs_minor_path\fR(\fBdi_minor_t\fR \fIminor\fR);
.fi

.LP
.nf
\fBchar *\fR\fBdi_path_devfs_path\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.LP
.nf
\fBchar *\fR\fBdi_path_client_devfs_path\fR(\fBdi_path_t\fR \fIpath\fR);
.fi

.LP
.nf
\fBvoid\fR \fBdi_devfs_path_free\fR(\fBchar *\fR\fIpath_buf\fR);
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fInode\fR\fR
.ad
.RS 12n
The handle to a device node in a \fBdi_init\fR(3DEVINFO) snapshot.
.RE

.sp
.ne 2
.na
\fB\fIminor\fR\fR
.ad
.RS 12n
The handle to a device minor node in a snapshot.
.RE

.sp
.ne 2
.na
\fB\fIpath\fR\fR
.ad
.RS 12n
The handle to a device path node in a snapshot.
.RE

.sp
.ne 2
.na
\fB\fIpath_buf\fR\fR
.ad
.RS 12n
A pointer returned by \fBdi_devfs_path()\fR, \fBdi_devfs_minor_path()\fR,
\fBdi_path_devfs_path()\fR, or \fBdi_path_client_devfs_path()\fR.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdi_devfs_path()\fR function generates the physical path of the device
node specified by \fInode\fR.
.sp
.LP
The \fBdi_devfs_minor_path()\fR function generates the physical path of the
device minor node specified by \fIminor\fR.
.sp
.LP
The \fBdi_path_devfs_path()\fR function generates the pHCI physical path to the
device associated with the specified path node. The returned string is
identical to the \fBdi_devfs_path()\fR  for the device had the device not been
supported by multipath.
.sp
.LP
The \fBdi_path_client_devfs_path()\fR function generates the vHCI physical path
of the multipath client device node associated with the device identity of the
specified path node. The returned string is identical to the
\fBdi_devfs_path()\fR of the multipath client device node.
.sp
.LP
The \fBdi_devfs_path_free()\fR function frees memory that was allocated to
store the path returned by \fBdi_devfs_path()\fR, \fBdi_devfs_minor_path()\fR,
\fBdi_path_devfs_path()\fR, and \fBdi_path_client_devfs_path()\fR. The caller
is responsible for freeing this memory by calling \fBdi_devfs_path_free()\fR.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the \fBdi_devfs_path()\fR,
\fBdi_devfs_minor_path()\fR, \fBdi_path_devfs_path()\fR, and
\fBdi_path_client_devfs_path()\fR functions return a pointer to the string
containing the path to a device node, a device minor node, or a device path
node, respectively. Otherwise, they return \fINULL\fR and \fBerrno\fR is set to
indicate the error. For a non-NULL return, the path will not have a
"/\fBdevices\fR" prefix.
.SH ERRORS
.sp
.LP
The \fBdi_devfs_path()\fR, \fBdi_devfs_minor_path()\fR,
\fBdi_path_devfs_path()\fR, and \fBdi_path_client_devfs_path()\fR functions
will fail if:
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fInode\fR, \fIminor\fR, or \fIpath\fR argument is not a valid handle.
.RE

.sp
.LP
The \fBdi_devfs_path()\fR, \fBdi_devfs_minor_path()\fR,
\fBdi_path_devfs_path()\fR, and \fBdi_path_client_devfs_path()\fR functions can
also return any error value returned by \fBmalloc\fR(3C).
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7)  for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
.TE

.SH SEE ALSO
.sp
.LP
.BR malloc (3C),
.BR di_init (3DEVINFO),
.BR libdevinfo (3LIB),
.BR attributes (7)
.sp
.LP
\fIWriting Device Drivers\fR