usr/src/man/man3c/rctl_walk.3c

   1 '\" te
   2 .\" Copyright (c) 2001, 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 RCTL_WALK 3C "Jan 1, 2001"
   7 .SH NAME
   8 rctl_walk \- visit registered rctls on current system
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <rctl.h>
  13
  14 \fBint\fR \fBrctl_walk\fR(\fBint (*\fR\fIcallback\fR)(const char *\fIrctlname\fR, void *\fIwalk_data\fR),
  15      \fBvoid *\fR\fIinit_data\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBrctl_walk()\fR function provides a mechanism for the application author
  22 to examine all active resource controls (rctls) on the current system.  The
  23 \fIcallback\fR function provided by the application is given the name of an
  24 rctl at each invocation and can use the \fIwalk_data\fR to record its own
  25 state. The callback function should return non-zero if it encounters an error
  26 condition or attempts to terminate the walk prematurely; otherwise the callback
  27 function should return 0.
  28 .SH RETURN VALUES
  29 .sp
  30 .LP
  31 Upon successful completion, \fBrctl_walk()\fR returns 0. It returns \(mi1 if
  32 the \fIcallback\fR function returned a non-zero value or if the walk
  33 encountered an error, in which case \fBerrno\fR is set to indicate the error.
  34 .SH ERRORS
  35 .sp
  36 .LP
  37 The \fBrctl_walk()\fR function will fail if:
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fBENOMEM\fR\fR
  42 .ad
  43 .RS 10n
  44 There is insufficient memory available to set up the initial data for the walk.
  45 .RE
  46
  47 .sp
  48 .LP
  49 Other returned error values are presumably caused by the \fIcallback\fR
  50 function.
  51 .SH EXAMPLES
  52 .LP
  53 \fBExample 1 \fRCount the number of rctls available on the system.
  54 .sp
  55 .LP
  56 The following example counts the number of resource controls on the system.
  57
  58 .sp
  59 .in +2
  60 .nf
  61 #include <sys/types.h>
  62 #include <rctl.h>
  63 #include <stdio.h>
  64
  65 typedef struct wdata {
  66      uint_t count;
  67 } wdata_t;
  68
  69 wdata_t total_count;
  70
  71 int
  72 simple_callback(const char *name, void *pvt)
  73 {
  74      wdata_t *w = (wdata_t *)pvt;
  75      w->count++;
  76      return (0);
  77 }
  78
  79 \&...
  80
  81 total_count.count = 0;
  82 errno = 0;
  83 if (rctl_walk(simple_callback, &total_count)) == 0)
  84      (void) printf("count = %u\en", total_count.count);
  85 .fi
  86 .in -2
  87
  88 .SH ATTRIBUTES
  89 .sp
  90 .LP
  91 See \fBattributes\fR(5) for descriptions of the following attributes:
  92 .sp
  93
  94 .sp
  95 .TS
  96 box;
  97 c | c
  98 l | l .
  99 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 100 _
 101 Interface Stability     Evolving
 102 _
 103 MT-Level        MT-Safe
 104 .TE
 105
 106 .SH SEE ALSO
 107 .sp
 108 .LP
 109 \fBsetrctl\fR(2), \fBattributes\fR(5)