1 '\" te
   2 .\"  Copyright (c) 1996, 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 CSX_GETFIRSTTUPLE 9F "Dec 20, 1996"
   7 .SH NAME
   8 csx_GetFirstTuple, csx_GetNextTuple \- return Card Information Structure tuple
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/pccard.h>
  13 
  14 
  15 
  16 \fBint32_t\fR \fBcsx_GetFirstTuple\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR);
  17 .fi
  18 
  19 .LP
  20 .nf
  21 \fBint32_t\fR \fBcsx_GetNextTuple\fR(\fBclient_handle_t\fR \fIch\fR, \fBtuple_t *\fR\fItu\fR);
  22 .fi
  23 
  24 .SH INTERFACE LEVEL
  25 .sp
  26 .LP
  27 Solaris \fBDDI \fRSpecific (Solaris \fBDDI) \fR
  28 .SH PARAMETERS
  29 .sp
  30 .ne 2
  31 .na
  32 \fB\fIch\fR\fR
  33 .ad
  34 .RS 6n
  35 Client handle returned from \fBcsx_RegisterClient\fR(9F).
  36 .RE
  37 
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fItu\fR\fR
  42 .ad
  43 .RS 6n
  44 Pointer to a \fBtuple_t\fR structure.
  45 .RE
  46 
  47 .SH DESCRIPTION
  48 .sp
  49 .LP
  50 The functions \fBcsx_GetFirstTuple()\fR and \fBcsx_GetNextTuple()\fR return the
  51 first and next tuple, respectively, of the specified type in the Card
  52 Information Structure (CIS) for the specified socket.
  53 .SH STRUCTURE MEMBERS
  54 .sp
  55 .LP
  56 The structure members of \fBtuple_t\fR are:
  57 .sp
  58 .in +2
  59 .nf
  60 uint32_t    Socket;        /* socket number */
  61 uint32_t    Attributes;    /* Attributes */
  62 cisdata_t   DesiredTuple;  /* tuple to search for or flags */
  63 cisdata_t   TupleCode;     /* tuple type code */
  64 cisdata_t   TupleLink;     /* tuple data body size */
  65 .fi
  66 .in -2
  67 
  68 .sp
  69 .LP
  70 The fields are defined as follows:
  71 .sp
  72 .ne 2
  73 .na
  74 \fB\fBSocket\fR\fR
  75 .ad
  76 .RS 23n
  77 Not used in Solaris, but for portability with other Card Services
  78 implementations, it should be set to the logical socket number.
  79 .RE
  80 
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBAttributes\fR\fR
  85 .ad
  86 .RS 23n
  87 This field is bit-mapped. The following bits are defined:
  88 .sp
  89 .ne 2
  90 .na
  91 \fBTUPLE_RETURN_LINK\fR
  92 .ad
  93 .sp .6
  94 .RS 4n
  95 Return link tuples if set. The following are link tuples and will only be
  96 returned by this function if the \fBTUPLE_RETURN_LINK\fR bit in the
  97 \fBAttributes\fR field is set:
  98 .sp
  99 .in +2
 100 .nf
 101         CISTPL_NULL     CISTPL_LONGLINK_MFC
 102         CISTPL_LONGLINK_A       CISTPL_LINKTARGET
 103         CISTPL_LONGLINK_C       CISTPL_NO_LINK
 104         CISTPL_LONGLINK_CB      CISTPL_END
 105 .fi
 106 .in -2
 107 
 108 .RE
 109 
 110 .sp
 111 .ne 2
 112 .na
 113 \fBTUPLE_RETURN_IGNORED_TUPLES\fR
 114 .ad
 115 .sp .6
 116 .RS 4n
 117 Return ignored tuples if set. Ignored tuples will be returned by this function
 118 if the \fBTUPLE_RETURN_IGNORED_TUPLES\fR bit in the \fBAttributes\fR field is
 119 set, see \fBtuple\fR(9S) for more information. The \fBCIS \fRis parsed from the
 120 location setup by the previous \fBcsx_GetFirstTuple()\fR or
 121 \fBcsx_GetNextTuple()\fR request.
 122 .RE
 123 
 124 .RE
 125 
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBDesiredTuple\fR\fR
 130 .ad
 131 .RS 23n
 132 This field is the tuple value desired. If it is \fBRETURN_FIRST_TUPLE,\fR the
 133 very first tuple of the \fBCIS \fRis returned (if it exists). If this field is
 134 set to \fBRETURN_NEXT_TUPLE,\fR the very next tuple of the \fBCIS \fRis
 135 returned (if it exists). If the \fBDesiredTuple\fR field is any other value on
 136 entry, the \fBCIS \fRis searched in an attempt to locate a tuple which matches.
 137 .RE
 138 
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBTupleCode,TupleLink\fR\fR
 143 .ad
 144 .RS 23n
 145 These fields are the values returned from the tuple found. If there are no
 146 tuples on the card, \fBCS_NO_MORE_ITEMS\fR is returned.
 147 .RE
 148 
 149 .sp
 150 .LP
 151 Since the \fBcsx_GetFirstTuple()\fR, \fBcsx_GetNextTuple()\fR, and
 152 \fBcsx_GetTupleData\fR(9F) functions all share the same \fBtuple_t\fR
 153 structure, some fields in the \fBtuple_t\fR structure are unused or reserved
 154 when calling this function and these fields must not be initialized by the
 155 client.
 156 .SH RETURN VALUES
 157 .sp
 158 .ne 2
 159 .na
 160 \fB\fBCS_SUCCESS\fR\fR
 161 .ad
 162 .RS 27n
 163 Successful operation.
 164 .RE
 165 
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBCS_BAD_HANDLE\fR\fR
 170 .ad
 171 .RS 27n
 172 Client handle is invalid.
 173 .RE
 174 
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBCS_NO_CARD\fR\fR
 179 .ad
 180 .RS 27n
 181 No \fBPC \fRCard in socket.
 182 .RE
 183 
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBCS_NO_CIS\fR\fR
 188 .ad
 189 .RS 27n
 190 No Card Information Structure (CIS) on \fBPC \fRcard.
 191 .RE
 192 
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fBCS_NO_MORE_ITEMS\fR\fR
 197 .ad
 198 .RS 27n
 199 Desired tuple not found.
 200 .RE
 201 
 202 .sp
 203 .ne 2
 204 .na
 205 \fB\fBCS_UNSUPPORTED_FUNCTION\fR\fR
 206 .ad
 207 .RS 27n
 208 No \fBPCMCIA \fRhardware installed.
 209 .RE
 210 
 211 .SH CONTEXT
 212 .sp
 213 .LP
 214 These functions may be called from user or kernel context.
 215 .SH SEE ALSO
 216 .sp
 217 .LP
 218 \fBcsx_GetTupleData\fR(9F), \fBcsx_ParseTuple\fR(9F),
 219 \fBcsx_RegisterClient\fR(9F), \fBcsx_ValidateCIS\fR(9F), \fBtuple\fR(9S)
 220 .sp
 221 .LP
 222 \fIPC Card \fR\fI95Standard,\fR PCMCIA/JEIDA