src/native_client/src/shared/gio/gio.h

   1 /*
   2  * Copyright (c) 2012 The Native Client Authors. All rights reserved.
   3  * Use of this source code is governed by a BSD-style license that can be
   4  * found in the LICENSE file.
   5  */
   6
   7 /*
   8  * NaCl Generic I/O interface.
   9  */
  10
  11 #ifndef NATIVE_CLIENT_SRC_SHARED_GIO_GIO_H_
  12 #define NATIVE_CLIENT_SRC_SHARED_GIO_GIO_H_
  13
  14 /* is this needed? - maybe for size_t */
  15 #include "native_client/src/include/portability.h"
  16
  17 #include <stdarg.h>
  18 #include <stdio.h>
  19
  20 EXTERN_C_BEGIN
  21
  22 struct Gio;  /* fwd */
  23
  24 /*
  25  * In the generic I/O package, -1 is used consistently to indicate
  26  * error.  Check the return value for equality to -1 and do not check
  27  * that it's negative.
  28  *
  29  * Here's the rationale.  Note that the Read and Write virtual
  30  * functions, like the read/write system calls, return ssize_t but
  31  * takes a count argument that's of type size_t.  Since
  32  * sizeof(ssize_t) == sizeof(size_t), this means that we either never
  33  * perform the full operation if the count argument would be negative
  34  * if viewed as an ssize_t, or we just do it and expect the caller to
  35  * do the right thing.  The only negative value that we reserve as an
  36  * error indication is -1, and this is also an unreasonable input
  37  * value on any sane, von-Neumann machine: there must be at least one
  38  * byte of code in the address space, and at least for Read, is
  39  * read-only text, and for Write it is extremely unlikely that any
  40  * application will want to write out (almost) the entire address
  41  * space.
  42  *
  43  * When -1 is used to indicate an error, errno is set to indicate the
  44  * error.
  45  */
  46 struct GioVtbl {
  47   /*
  48    * Will implicitly close if not already closed, but no error
  49    * reporting, other than possibly logging.
  50    */
  51   void    (*Dtor)(struct Gio  *vself);
  52
  53   /*
  54    * Read virtual fn.  Like read syscall: returns number of bytes
  55    * actually read, -1 on error, so 0 indcates EOF.  Depending on
  56    * subclass, there may be short reads even before EOF, but all short
  57    * reads must return at least one byte, so that this is
  58    * distinguishable from EOF.
  59    */
  60   ssize_t (*Read)(struct Gio  *vself,
  61                    void       *buf,
  62                    size_t     count);
  63
  64   /*
  65    * Write virtual fn.  Like write syscall: returns number of bytes
  66    * actually written, -1 on error.  Depending on subclass, there may
  67    * be short writes.
  68    */
  69   ssize_t (*Write)(struct Gio *vself,
  70                    const void *buf,
  71                    size_t     count);
  72
  73   /*
  74    * Seek virtual function.  Like the lseek syscall.  whence is one of
  75    * SEEK_SET, SEEK_CUR, SEEK_END.  There is no ftell -- use
  76    * Seek(self, 0, SEEK_CUR) to obtain the current position.  Whether
  77    * seeking beyond the end of an Gio object and writing results in
  78    * defined behavior depends on the subclass involved, i.e., some
  79    * subclasses may grow/extend the object (e.g., file, shared
  80    * memory), and others may not (e.g., in-memory snapshot).
  81    */
  82   off_t   (*Seek)(struct Gio  *vself,
  83                   off_t       offset,
  84                   int         whence);
  85
  86   /* Only used for write, 0 on success, -1 on error */
  87   int     (*Flush)(struct Gio *vself);
  88
  89   /*
  90    * Returns 0 on success, -1 on error.  Implicitly Flush.  If Flush
  91    * succeeds, deallocate system-level resources.  After Close, no
  92    * other operations should be performed other than Dtor.  Close
  93    * might be merged with the Dtor, except that the Dtor cannot report
  94    * errors.
  95    */
  96   int     (*Close)(struct Gio *vself);
  97 };
  98
  99 struct Gio {
 100   struct GioVtbl const    *vtbl;
 101 };
 102
 103 struct GioFile {
 104   struct Gio  base;
 105   FILE        *iop;
 106 };
 107
 108 int GioFileCtor(struct GioFile  *self,
 109                 char const      *fname,
 110                 char const      *mode);
 111
 112 ssize_t GioFileRead(struct Gio  *vself,
 113                     void        *buf,
 114                     size_t      count);
 115
 116 ssize_t GioFileWrite(struct Gio *vself,
 117                      const void *buf,
 118                      size_t     count);
 119
 120 off_t GioFileSeek(struct Gio  *vself,
 121                   off_t       offset,
 122                   int         whence);
 123
 124 int GioFileFlush(struct Gio *vself);
 125
 126 int GioFileClose(struct Gio *vself);
 127
 128 void  GioFileDtor(struct Gio  *vself);
 129
 130 int GioFileRefCtor(struct GioFile *self,
 131                    FILE           *iop);
 132
 133
 134 size_t gprintf(struct Gio  *gp,
 135                char const  *fmt,
 136                ...);
 137
 138 size_t gvprintf(struct Gio *gp,
 139                 char const *fmt,
 140                 va_list    ap);
 141
 142 EXTERN_C_END
 143
 144 #endif  /* NATIVE_CLIENT_SRC_SHARED_GIO_GIO_H_ */