share/man/man3devinfo/di_devlink_init.3devinfo

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH DI_DEVLINK_INIT 3DEVINFO "Jul 21, 2008"
   7 .SH NAME
   8 di_devlink_init, di_devlink_fini \- create and destroy a snapshot of devlinks
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-ldevinfo\fR [ \fIlibrary\fR... ]
  13 #include <libdevinfo.h>
  14
  15 \fBdi_devlink_handle_t\fR \fBdi_devlink_init\fR(\fBconst char *\fR\fIname\fR,
  16      \fBuint_t\fR \fIflags\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBint\fR \fBdi_devlink_fini\fR(\fBdi_devlink_handle_t *\fR\fIhdlp\fR);
  22 .fi
  23
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIflags\fR\fR
  29 .ad
  30 .RS 9n
  31 The following values are supported:
  32 .sp
  33 .ne 2
  34 .na
  35 \fB\fBDI_MAKE_LINK\fR\fR
  36 .ad
  37 .RS 16n
  38 Synchronize with devlink management before taking the snapshot. The name
  39 argument determines which devlink management activities must complete before
  40 taking a devlink snapshot. Appropriate privileges are required to use this
  41 flag.
  42 .RE
  43
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIname\fR\fR
  50 .ad
  51 .RS 9n
  52 If flags is \fBDI_MAKE_LINK\fR, \fIname\fR determines which devlink management
  53 activity must complete prior to snapshot.
  54 .RS +4
  55 .TP
  56 .ie t \(bu
  57 .el o
  58 If \fIname\fR is \fINULL\fR then all devlink management activities must
  59 complete. The devlink snapshot returned accurately reflects the entire kernel
  60 device tree.
  61 .RE
  62 .RS +4
  63 .TP
  64 .ie t \(bu
  65 .el o
  66 If \fIname\fR is a driver name, devlink management activities associated with
  67 nodes bound to that driver must complete.
  68 .RE
  69 .RS +4
  70 .TP
  71 .ie t \(bu
  72 .el o
  73 If \fIname\fR is a path to a node in the kernel device tree (no
  74 "\fB/devices\fR" prefix), devlink management activities below node must
  75 complete.
  76 .RE
  77 .RS +4
  78 .TP
  79 .ie t \(bu
  80 .el o
  81 If \fIname\fR is a path to a minor node in the kernel device tree (no
  82 "\fB/devices\fR"prefix), devlink management activities on that minor node must
  83 complete.
  84 .RE
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIhdlp\fR\fR
  91 .ad
  92 .RS 9n
  93 The handle to the snapshot obtained by calling \fBdi_devlink_init()\fR.
  94 .RE
  95
  96 .SH DESCRIPTION
  97 .sp
  98 .LP
  99 System management applications often need to map a "\fB/devices\fR" path to a
 100 minor node to a public "\fB/dev\fR" device name. The \fBdi_devlink_*()\fR
 101 functions provide an efficient way to accomplish this.
 102 .sp
 103 .LP
 104 The \fBdi_devlink_init()\fR function takes a snapshot of devlinks and returns a
 105 handle to this snapshot.
 106 .sp
 107 .LP
 108 The \fBdi_devlink_fini()\fR function destroys the devlink snapshot and frees
 109 the associated memory.
 110 .SH RETURN VALUES
 111 .sp
 112 .LP
 113 Upon successful completion, \fBdi_devlink_init()\fR returns a handle to a
 114 devlink snapshot. Otherwise, \fBDI_LINK_NIL\fR is returned and \fBerrno\fR is
 115 set to indicate the error.
 116 .sp
 117 .LP
 118 Upon successful completion, \fBdi_devlink_fini()\fR returns 0. Otherwise, -1 is
 119 returned and \fBerrno\fR is set to indicate the error.
 120 .SH ERRORS
 121 .sp
 122 .LP
 123 The \fBdi_devlink_init()\fR function will fail if:
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fBEINVAL\fR\fR
 128 .ad
 129 .RS 10n
 130 One or more arguments is invalid.
 131 .RE
 132
 133 .sp
 134 .LP
 135 The \fBdi_devlink_init()\fR function with \fBDI_MAKE_LINK\fR can also fail if:
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fBEPERM\fR\fR
 140 .ad
 141 .RS 9n
 142 The user does no have appropriate privileges.
 143 .RE
 144
 145 .sp
 146 .LP
 147 The \fBdi_devlink_init()\fR function can set \fBerrno\fR to any error value
 148 that can also be set by \fBmalloc\fR(3C), \fBopen\fR(2), \fBioctl\fR(2), or
 149 \fBmmap\fR(2).
 150 .SH ATTRIBUTES
 151 .sp
 152 .LP
 153 See \fBattributes\fR(5)  for descriptions of the following attributes:
 154 .sp
 155
 156 .sp
 157 .TS
 158 box;
 159 c | c
 160 l | l .
 161 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 162 _
 163 Interface Stability     Committed
 164 _
 165 MT-Level        Safe
 166 .TE
 167
 168 .SH SEE ALSO
 169 .sp
 170 .LP
 171 \fBioctl\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBdi_devlink_path\fR(3DEVINFO),
 172 \fBdi_devlink_walk\fR(3DEVINFO), \fBlibdevinfo\fR(3LIB), \fBmalloc\fR(3C),
 173 \fBattributes\fR(5)