doc/html/ref/fileio-file-table.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >File Table</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="File System Support Infrastructure"
  23 HREF="fileio.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Mount Table"
  26 HREF="fileio-mount-table.html"><LINK
  27 REL="NEXT"
  28 TITLE="Directories"
  29 HREF="fileio-directories.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="fileio-mount-table.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="fileio-directories.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="FILEIO-FILE-TABLE">Chapter 22. File Table</H1
  85 ><P
  86 >Once a file has been opened it is represented by an open file
  87 object. These are allocated from an array of available file
  88 objects. User code accesses these open file objects via a second array
  89 of pointers which is indexed by small integer offsets. This gives the
  90 usual Unix file descriptor functionality, complete with the various
  91 duplication mechanisms.</P
  92 ><P
  93 >A file table entry has the following structure:</P
  94 ><TABLE
  95 BORDER="5"
  96 BGCOLOR="#E0E0F0"
  97 WIDTH="70%"
  98 ><TR
  99 ><TD
 100 ><PRE
 101 CLASS="PROGRAMLISTING"
 102 >struct CYG_FILE_TAG
 103 {
 104     cyg_uint32                  f_flag;         /* file state                   */
 105     cyg_uint16                  f_ucount;       /* use count                    */
 106     cyg_uint16                  f_type;         /* descriptor type              */
 107     cyg_uint32                  f_syncmode;     /* synchronization protocol     */
 108     struct CYG_FILEOPS_TAG      *f_ops;         /* file operations              */
 109     off_t                       f_offset;       /* current offset               */
 110     CYG_ADDRWORD                f_data;         /* file or socket               */
 111     CYG_ADDRWORD                f_xops;         /* extra type specific ops      */
 112     cyg_mtab_entry              *f_mte;         /* mount table entry            */
 113 };</PRE
 114 ></TD
 115 ></TR
 116 ></TABLE
 117 ><P
 118 >The <TT
 119 CLASS="STRUCTFIELD"
 120 ><I
 121 >f_flag</I
 122 ></TT
 123 > field contains some FILEIO
 124 control bits and some bits propagated from the
 125 <TT
 126 CLASS="PARAMETER"
 127 ><I
 128 >flags</I
 129 ></TT
 130 > argument of the
 131 <TT
 132 CLASS="FUNCTION"
 133 >open()</TT
 134 > call (defined by
 135 <TT
 136 CLASS="LITERAL"
 137 >CYG_FILE_MODE_MASK</TT
 138 >).</P
 139 ><P
 140 >The <TT
 141 CLASS="STRUCTFIELD"
 142 ><I
 143 >f_ucount</I
 144 ></TT
 145 > field contains a use count that
 146 controls when a file will be closed. Each duplicate in the file
 147 descriptor array counts for one reference here. It is also
 148 incremented around each I/O operation to ensure that the file cannot
 149 be closed while it has current I/O operations.</P
 150 ><P
 151 >The <TT
 152 CLASS="STRUCTFIELD"
 153 ><I
 154 >f_type</I
 155 ></TT
 156 > field indicates the type of the
 157 underlying file object. Some of the possible values here are
 158 <TT
 159 CLASS="LITERAL"
 160 >CYG_FILE_TYPE_FILE</TT
 161 >,
 162 <TT
 163 CLASS="LITERAL"
 164 >CYG_FILE_TYPE_SOCKET</TT
 165 > or <TT
 166 CLASS="LITERAL"
 167 >CYG_FILE_TYPE_DEVICE</TT
 168 >.</P
 169 ><P
 170 >The <TT
 171 CLASS="STRUCTFIELD"
 172 ><I
 173 >f_syncmode</I
 174 ></TT
 175 > field is copied from the
 176 <TT
 177 CLASS="STRUCTFIELD"
 178 ><I
 179 >syncmode</I
 180 ></TT
 181 > field of the implementing
 182 filesystem. Its use is described in <A
 183 HREF="fileio-synchronization.html"
 184 >Chapter 24</A
 185 >.</P
 186 ><P
 187 >The <TT
 188 CLASS="STRUCTFIELD"
 189 ><I
 190 >f_offset</I
 191 ></TT
 192 > field records the current file
 193 position. It is the responsibility of the file operation functions to
 194 keep this field up to date.</P
 195 ><P
 196 >The <TT
 197 CLASS="STRUCTFIELD"
 198 ><I
 199 >f_data</I
 200 ></TT
 201 > field contains private data
 202 placed here by the underlying filesystem. Normally this will be a
 203 pointer to, or handle on, the filesystem object that implements this
 204 file.</P
 205 ><P
 206 >The <TT
 207 CLASS="STRUCTFIELD"
 208 ><I
 209 >f_xops</I
 210 ></TT
 211 > field contains a pointer to any
 212 extra type specific operation functions. For example, the socket I/O
 213 system installs a pointer to a table of functions that implement the
 214 standard socket operations.</P
 215 ><P
 216 >The <TT
 217 CLASS="STRUCTFIELD"
 218 ><I
 219 >f_mte</I
 220 ></TT
 221 > field contains a pointer to the
 222 parent mount table entry for this file. It is used mainly to implement
 223 the synchronization protocol. This may contain a pointer to some other
 224 data structure in file objects not derived from a filesystem.</P
 225 ><P
 226 >The <TT
 227 CLASS="STRUCTFIELD"
 228 ><I
 229 >f_ops</I
 230 ></TT
 231 > field contains a pointer to a
 232 table of file I/O operations. This has the following structure:</P
 233 ><TABLE
 234 BORDER="5"
 235 BGCOLOR="#E0E0F0"
 236 WIDTH="70%"
 237 ><TR
 238 ><TD
 239 ><PRE
 240 CLASS="PROGRAMLISTING"
 241 >struct CYG_FILEOPS_TAG
 242 {
 243         int     (*fo_read)      (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
 244         int     (*fo_write)     (struct CYG_FILE_TAG *fp, struct CYG_UIO_TAG *uio);
 245         int     (*fo_lseek)     (struct CYG_FILE_TAG *fp, off_t *pos, int whence );
 246         int     (*fo_ioctl)     (struct CYG_FILE_TAG *fp, CYG_ADDRWORD com,
 247                                  CYG_ADDRWORD data);
 248         int     (*fo_select)    (struct CYG_FILE_TAG *fp, int which, CYG_ADDRWORD info);
 249         int     (*fo_fsync)     (struct CYG_FILE_TAG *fp, int mode );
 250         int     (*fo_close)     (struct CYG_FILE_TAG *fp);
 251         int     (*fo_fstat)     (struct CYG_FILE_TAG *fp, struct stat *buf );
 252         int     (*fo_getinfo)   (struct CYG_FILE_TAG *fp, int key, char *buf, int len );
 253         int     (*fo_setinfo)   (struct CYG_FILE_TAG *fp, int key, char *buf, int len );
 254 };</PRE
 255 ></TD
 256 ></TR
 257 ></TABLE
 258 ><P
 259 >It should be obvious from the names of most of these functions what
 260 their responsibilities are. The <TT
 261 CLASS="FUNCTION"
 262 >fo_getinfo()</TT
 263 >
 264 and <TT
 265 CLASS="FUNCTION"
 266 >fo_setinfo()</TT
 267 > function pointers, like their
 268 counterparts in the filesystem structure, implement minor control and
 269 info functions such as <TT
 270 CLASS="FUNCTION"
 271 >fpathconf()</TT
 272 >.</P
 273 ><P
 274 >The second argument to the <TT
 275 CLASS="FUNCTION"
 276 >fo_read()</TT
 277 > and
 278 <TT
 279 CLASS="FUNCTION"
 280 >fo_write()</TT
 281 > function pointers is a pointer to a
 282 UIO structure:</P
 283 ><TABLE
 284 BORDER="5"
 285 BGCOLOR="#E0E0F0"
 286 WIDTH="70%"
 287 ><TR
 288 ><TD
 289 ><PRE
 290 CLASS="PROGRAMLISTING"
 291 >struct CYG_UIO_TAG
 292 {
 293     struct CYG_IOVEC_TAG *uio_iov;      /* pointer to array of iovecs */
 294     int                  uio_iovcnt;    /* number of iovecs in array */
 295     off_t                uio_offset;    /* offset into file this uio corresponds to */
 296     ssize_t              uio_resid;     /* residual i/o count */
 297     enum cyg_uio_seg     uio_segflg;    /* see above */
 298     enum cyg_uio_rw      uio_rw;        /* see above */
 299 };
 300
 301 struct CYG_IOVEC_TAG
 302 {
 303     void           *iov_base;           /* Base address. */
 304     ssize_t        iov_len;             /* Length. */
 305 };</PRE
 306 ></TD
 307 ></TR
 308 ></TABLE
 309 ><P
 310 >This structure encapsulates the parameters of any data transfer
 311 operation. It provides support for scatter/gather operations and
 312 records the progress of any data transfer. It is also compatible with
 313 the I/O operations of any BSD-derived network stacks and filesystems.</P
 314 ><P
 315 >When a file is opened (or a file object created by some other means,
 316 such as <TT
 317 CLASS="FUNCTION"
 318 >socket()</TT
 319 > or <TT
 320 CLASS="FUNCTION"
 321 >accept()</TT
 322 >) it is the
 323 responsibility of the filesystem open operation to initialize all the
 324 fields of the object except the <TT
 325 CLASS="STRUCTFIELD"
 326 ><I
 327 >f_ucount</I
 328 ></TT
 329 >,
 330 <TT
 331 CLASS="STRUCTFIELD"
 332 ><I
 333 >f_syncmode</I
 334 ></TT
 335 > and
 336 <TT
 337 CLASS="STRUCTFIELD"
 338 ><I
 339 >f_mte</I
 340 ></TT
 341 > fields. Since the
 342 <TT
 343 CLASS="STRUCTFIELD"
 344 ><I
 345 >f_flag</I
 346 ></TT
 347 > field will already contain bits belonging to the FILEIO
 348 infrastructure, any changes to it must be made with the appropriate
 349 logical operations.</P
 350 ></DIV
 351 ><DIV
 352 CLASS="NAVFOOTER"
 353 ><HR
 354 ALIGN="LEFT"
 355 WIDTH="100%"><TABLE
 356 SUMMARY="Footer navigation table"
 357 WIDTH="100%"
 358 BORDER="0"
 359 CELLPADDING="0"
 360 CELLSPACING="0"
 361 ><TR
 362 ><TD
 363 WIDTH="33%"
 364 ALIGN="left"
 365 VALIGN="top"
 366 ><A
 367 HREF="fileio-mount-table.html"
 368 ACCESSKEY="P"
 369 >Prev</A
 370 ></TD
 371 ><TD
 372 WIDTH="34%"
 373 ALIGN="center"
 374 VALIGN="top"
 375 ><A
 376 HREF="ecos-ref.html"
 377 ACCESSKEY="H"
 378 >Home</A
 379 ></TD
 380 ><TD
 381 WIDTH="33%"
 382 ALIGN="right"
 383 VALIGN="top"
 384 ><A
 385 HREF="fileio-directories.html"
 386 ACCESSKEY="N"
 387 >Next</A
 388 ></TD
 389 ></TR
 390 ><TR
 391 ><TD
 392 WIDTH="33%"
 393 ALIGN="left"
 394 VALIGN="top"
 395 >Mount Table</TD
 396 ><TD
 397 WIDTH="34%"
 398 ALIGN="center"
 399 VALIGN="top"
 400 ><A
 401 HREF="fileio.html"
 402 ACCESSKEY="U"
 403 >Up</A
 404 ></TD
 405 ><TD
 406 WIDTH="33%"
 407 ALIGN="right"
 408 VALIGN="top"
 409 >Directories</TD
 410 ></TR
 411 ></TABLE
 412 ></DIV
 413 ></BODY
 414 ></HTML
 415 >