share/man/man3project/project_walk.3project

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