usr/src/man/man9f/drv_getparm.9f

   1 '\" te
   2 .\"  opyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" 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.
   5 .\" 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.
   6 .\" 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]
   7 .TH DRV_GETPARM 9F "Jan 16, 2006"
   8 .SH NAME
   9 drv_getparm \- retrieve kernel state information
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14
  15
  16
  17 \fBint\fR \fBdrv_getparm\fR(\fBunsigned int\fR \fIparm\fR, \fBvoid *\fR\fIvalue_p\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Architecture independent level 1 (DDI/DKI).
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIparm\fR\fR
  29 .ad
  30 .RS 8n
  31 The kernel parameter to be obtained. Possible values are:
  32 .RE
  33
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fBLBOLT\fR\fR
  38 .ad
  39 .RS 10n
  40 Read the value of \fBlbolt\fR. \fBlbolt\fR is a \fBclock_t\fR that is
  41 unconditionally incremented by one at each clock tick. No special treatment is
  42 applied when this value overflows the maximum value of the signed integral type
  43 \fBclock_t\fR. When this occurs, its value will be negative, and its magnitude
  44 will be decreasing until it again passes zero. It can therefore not be relied
  45 upon to provide an indication of the amount of time that passes since the last
  46 system reboot, nor should it be used to mark an absolute time in the system.
  47 Only the difference between two measurements of \fBlbolt\fR is significant. It
  48 is used in this way inside the system kernel for timing purposes.
  49 .RE
  50
  51 .sp
  52 .ne 2
  53 .na
  54 \fB\fBPPGRP\fR\fR
  55 .ad
  56 .RS 10n
  57 Read the process group identification number. This number determines which
  58 processes should receive a \fBHANGUP\fR or \fBBREAK\fR signal when detected by
  59 a driver.
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBUPROCP\fR\fR
  66 .ad
  67 .RS 10n
  68 Read the process table token value.
  69 .RE
  70
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBPPID\fR\fR
  75 .ad
  76 .RS 10n
  77 Read process identification number.
  78 .RE
  79
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fBPSID\fR\fR
  84 .ad
  85 .RS 10n
  86 Read process session identification number.
  87 .RE
  88
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fBTIME\fR\fR
  93 .ad
  94 .RS 10n
  95 Read time in seconds.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBUCRED\fR\fR
 102 .ad
 103 .RS 10n
 104 Return a pointer to the caller's credential structure.
 105 .RE
 106
 107 .sp
 108 .ne 2
 109 .na
 110 \fB\fIvalue_p\fR\fR
 111 .ad
 112 .RS 11n
 113 A pointer to the data space in which the value of the parameter is to be
 114 copied.
 115 .RE
 116
 117 .SH DESCRIPTION
 118 .sp
 119 .LP
 120 Since the release of the Solaris 2.6 operating environment, the
 121 \fBdrv_getparm()\fR function has been replaced by \fBddi_get_lbolt\fR(9F),
 122 \fBddi_get_time\fR(9F), and \fBddi_get_pid\fR(9F).
 123 .sp
 124 .LP
 125 The \fBdrv_getparm()\fR function verifies that \fIparm\fR corresponds to a
 126 kernel parameter that may be read. If the value of \fIparm\fR does not
 127 correspond to a parameter or corresponds to a parameter that may not be read,
 128 \fB-1\fR is returned. Otherwise, the value of the parameter is stored in the
 129 data space pointed to by \fIvalue_p\fR.
 130 .sp
 131 .LP
 132 The \fBdrv_getparm()\fR function does not explicitly check to see whether the
 133 device has the appropriate context when the function is called and the function
 134 does not check for correct alignment in the data space pointed to by
 135 \fIvalue_p\fR. It is the responsibility of the driver writer to use this
 136 function only when it is appropriate to do so and to correctly declare the data
 137 space needed by the driver.
 138 .SH RETURN VALUES
 139 .sp
 140 .LP
 141 The \fBdrv_getparm()\fR function returns \fB0\fR to indicate success, \fB-1\fR
 142 to indicate failure. The value stored in the space pointed to by \fIvalue_p\fR
 143 is the value of the parameter if \fB0\fR is returned, or undefined if \fB-1\fR
 144 is returned. \fB-1\fR is returned if you specify a value other than
 145 \fBLBOLT\fR, \fBPPGRP\fR, \fBPPID\fR, \fBPSID\fR, \fBTIME\fR, \fBUCRED\fR, or
 146 \fBUPROCP\fR. Always check the return code when using this function.
 147 .SH CONTEXT
 148 .sp
 149 .LP
 150 The \fBdrv_getparm()\fR function can be called from user context only when
 151 using \fBPPGRP\fR, \fBPPID\fR, \fBPSID\fR, \fBUCRED\fR, or \fBUPROCP\fR. It can
 152 be called from user, interrupt, or kernel context when using the \fBLBOLT\fR or
 153 \fBTIME\fR argument.
 154 .SH SEE ALSO
 155 .sp
 156 .LP
 157 \fBddi_get_lbolt\fR(9F), \fBddi_get_pid\fR(9F), \fBddi_get_time\fR(9F),
 158 \fBbuf\fR(9S)
 159 .sp
 160 .LP
 161 \fIWriting Device Drivers\fR