Current File : //usr/man/man9e/prop_op.9e

'\" te
.\" Copyright (c) 2000 Sun Microsystems, Inc.  All Rights Reserved
.TH prop_op 9E "8 Jul 1996" "SunOS 5.11" "Driver Entry Points"
.SH NAME
prop_op \- report driver property information
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <sys/ddi.h>
#include <sys/sunddi.h>

\fBint prefix\fR\fBprop_op\fR(\fBdev_t\fR \fIdev\fR, \fBdev_info_t *\fR\fIdip\fR, 
     \fBddi_prop_op_t\fR \fIprop_op\fR, \fBint\fR \fIflags\fR, \fBchar *\fR\fIname\fR, \fBcaddr_t\fR \fIvaluep\fR, 
     \fBint *\fR\fIlengthp\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI). This entry point is required, but it can be \fBddi_prop_op\fR(9F).
.SH ARGUMENTS
.sp
.ne 2
.mk
.na
\fB\fIdev\fR\fR
.ad
.RS 12n
.rt  
Device number associated with this device.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 12n
.rt  
A pointer to the  device information structure for this device.
.RE

.sp
.ne 2
.mk
.na
\fB\fIprop_op\fR\fR
.ad
.RS 12n
.rt  
Property operator. Valid operators are: 
.sp
.ne 2
.mk
.na
\fB\fBPROP_LEN\fR \fR
.ad
.RS 26n
.rt  
Get property length only. (\fIvaluep\fR unaffected).
.RE

.sp
.ne 2
.mk
.na
\fB\fBPROP_LEN_AND_VAL_BUF\fR\fR
.ad
.RS 26n
.rt  
Get length and value into caller's buffer. (\fIvaluep\fR used as input).
.RE

.sp
.ne 2
.mk
.na
\fB\fBPROP_LEN_AND_VAL_ALLOC\fR\fR
.ad
.RS 26n
.rt  
Get length and value into allocated buffer. (\fIvaluep\fR returned as pointer to pointer to allocated buffer).
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 12n
.rt  
The only possible flag value is: 
.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_DONTPASS\fR\fR
.ad
.RS 21n
.rt  
Do not pass request to parent if property not found.
.RE

.RE

.sp
.ne 2
.mk
.na
\fB\fIname\fR\fR
.ad
.RS 12n
.rt  
Pointer to name of property to be interrogated.
.RE

.sp
.ne 2
.mk
.na
\fB\fIvaluep\fR \fR
.ad
.RS 12n
.rt  
If  \fIprop_op\fR is  \fBPROP_LEN_AND_VAL_BUF\fR, this should be a pointer to the user's buffer.  If \fIprop_op\fR is \fBPROP_LEN_AND_VAL_ALLOC\fR, this should be the \fIaddress\fR of a pointer.
.RE

.sp
.ne 2
.mk
.na
\fB\fIlengthp\fR \fR
.ad
.RS 12n
.rt  
On exit,  *\fIlengthp\fR will contain the property length.  If \fIprop_op\fR is  \fBPROP_LEN_AND_VAL_BUF\fR then \fIlengthp\fR should point to an \fBint\fR that contains the length of caller's buffer,  before calling \fBprop_op()\fR. 
.RE

.SH DESCRIPTION
.sp
.LP
\fBprop_op()\fR is an entry point which reports the values of certain properties of the driver or device to the system. Each driver must have a \fIprefix\fR \fBprop_op\fR entry point, but most drivers that do not need to create or manage their own properties can use \fBddi_prop_op()\fR for this entry point.  Then the driver can use \fBddi_prop_update\fR(9F) to create properties for its device. 
.SH RETURN VALUES
.sp
.LP
\fBprop_op()\fR should return:
.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_SUCCESS\fR \fR
.ad
.RS 27n
.rt  
Property found and returned.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_NOT_FOUND\fR \fR
.ad
.RS 27n
.rt  
Property not found.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_UNDEFINED\fR \fR
.ad
.RS 27n
.rt  
Prop explicitly undefined.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_NO_MEMORY\fR \fR
.ad
.RS 27n
.rt  
Property found, but unable to allocate memory. \fIlengthp\fR has the correct property length.
.RE

.sp
.ne 2
.mk
.na
\fB\fBDDI_PROP_BUF_TOO_SMALL\fR \fR
.ad
.RS 27n
.rt  
Property found, but the supplied buffer is too small. \fIlengthp\fR has the correct property length.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBprop_op()\fR to Report Property Information
.sp
.LP
In the following example, \fBprop_op()\fR intercepts requests for the \fItemperature\fR property. The driver tracks changes to \fItemperature\fR using a variable in the state structure in order to avoid frequent calls to \fBddi_prop_update\fR(9F). The \fItemperature\fR property is only updated when a request is made for this property.  It then uses the system routine \fBddi_prop_op\fR(9F) to process the property request.  If the property request is not specific to a device, the driver does not intercept the request. This is indicated when the value of the  \fIdev\fR parameter is equal to \fBDDI_DEV_T_ANY\fR. 

.sp
.in +2
.nf
int temperature;	/* current device temperature */
 .
 .
 .
static int
xxprop_op(dev_t dev, dev_info_t *dip, ddi_prop_op_t prop_op,
     int flags, char *name, caddr_t valuep, int *lengthp)
{
			int  instance;
			struct xxstate *xsp;
     if (dev == DDI_DEV_T_ANY)
				goto skip;
     instance = getminor(dev);
     xsp = ddi_get_soft_state(statep, instance);
     if (xsp == NULL)
				return (DDI_PROP_NOT_FOUND);
     if (strcmp(name, "temperature") == 0) {
				ddi_prop_update_int(dev, dip,\e
           "temperature", temperature);
     }
		       /*	other cases...	*/
     skip:
     return (ddi_prop_op(dev, dip, prop_op, flags,\e 
             name, valuep, lengthp));
}
.fi
.in -2

.SH SEE ALSO
.sp
.LP
\fBIntro\fR(9E), \fBddi_prop_op\fR(9F), \fBddi_prop_update\fR(9F) 
.sp
.LP
\fIWriting Device Drivers for Oracle Solaris 11.2\fR