packages/language/c/libc/stdio/v2_0/include/stream.hxx

   1 #ifndef CYGONCE_LIBC_STDIO_STREAM_HXX
   2 #define CYGONCE_LIBC_STDIO_STREAM_HXX
   3 //========================================================================
   4 //
   5 //      stream.hxx
   6 //
   7 //      Internal C library stdio stream interface definitions
   8 //
   9 //========================================================================
  10 //####ECOSGPLCOPYRIGHTBEGIN####
  11 // -------------------------------------------
  12 // This file is part of eCos, the Embedded Configurable Operating System.
  13 // Copyright (C) 1998, 1999, 2000, 2001, 2002 Red Hat, Inc.
  14 //
  15 // eCos is free software; you can redistribute it and/or modify it under
  16 // the terms of the GNU General Public License as published by the Free
  17 // Software Foundation; either version 2 or (at your option) any later version.
  18 //
  19 // eCos is distributed in the hope that it will be useful, but WITHOUT ANY
  20 // WARRANTY; without even the implied warranty of MERCHANTABILITY or
  21 // FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  22 // for more details.
  23 //
  24 // You should have received a copy of the GNU General Public License along
  25 // with eCos; if not, write to the Free Software Foundation, Inc.,
  26 // 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
  27 //
  28 // As a special exception, if other files instantiate templates or use macros
  29 // or inline functions from this file, or you compile this file and link it
  30 // with other works to produce a work based on this file, this file does not
  31 // by itself cause the resulting work to be covered by the GNU General Public
  32 // License. However the source code for this file must still be made available
  33 // in accordance with section (3) of the GNU General Public License.
  34 //
  35 // This exception does not invalidate any other reasons why a work based on
  36 // this file might be covered by the GNU General Public License.
  37 //
  38 // Alternative licenses for eCos may be arranged by contacting Red Hat, Inc.
  39 // at http://sources.redhat.com/ecos/ecos-license/
  40 // -------------------------------------------
  41 //####ECOSGPLCOPYRIGHTEND####
  42 //========================================================================
  43 //#####DESCRIPTIONBEGIN####
  44 //
  45 // Author(s):     jlarmour
  46 // Contributors:
  47 // Date:          2001-03-16
  48 // Purpose:
  49 // Description:
  50 // Usage:         #include <cyg/libc/stdio/stream.hxx>
  51 //
  52 //####DESCRIPTIONEND####
  53 //
  54 //========================================================================
  55
  56 // CONFIGURATION
  57
  58 #include <pkgconf/libc_stdio.h>   // Configuration header
  59
  60 // INCLUDES
  61
  62 #include <cyg/infra/cyg_type.h>    // Common project-wide type definitions
  63 #include <cyg/infra/cyg_ass.h>     // Get assertion macros, as appropriate
  64 #include <errno.h>                 // Cyg_ErrNo
  65 #include <stdio.h>                 // fpos_t and IOBUF defines
  66 #include <cyg/libc/stdio/io.hxx>     // Physical IO support
  67 #include <cyg/libc/stdio/streambuf.hxx>  // Stdio stream file buffers
  68
  69 #ifdef CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS
  70 #include <pkgconf/kernel.h>
  71 #include <cyg/kernel/mutex.hxx>    // Cyg_Mutex
  72 #endif
  73
  74 // TYPE DEFINITIONS
  75
  76 class Cyg_StdioStream;
  77 __externC Cyg_ErrNo
  78 cyg_libc_stdio_flush_all_but( Cyg_StdioStream * );
  79
  80 class Cyg_StdioStream
  81 {
  82     friend int setvbuf( FILE *, char *, int, size_t ) __THROW;
  83     friend Cyg_ErrNo
  84     cyg_libc_stdio_flush_all_but( Cyg_StdioStream * );
  85
  86 private:
  87
  88     // error status for this file
  89     Cyg_ErrNo error;
  90
  91
  92     cyg_stdio_handle_t my_device;
  93
  94 #ifdef CYGFUN_LIBC_STDIO_ungetc
  95     cyg_uint8 unread_char_buf;
  96 #endif
  97
  98 #ifdef CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO
  99     Cyg_StdioStreamBuffer io_buf; // read/write buffer
 100 #endif
 101     cyg_uint8 readbuf_char; // a one character emergency "buffer"
 102                             // only used when configured to not buffer
 103                             // (i.e. !CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO)
 104                             // or set at runtime to not buffer (i.e.
 105                             // buffering mode is _IONBF)
 106
 107     // some flags indicating the state of the file. Some of it is internal
 108     // state, which should not be public. Use bitfields to save
 109     // space, which means using "unsigned int" rather than cyg_uintX
 110     struct {
 111         unsigned int at_eof                  : 1; // Have we reached eof?
 112
 113         unsigned int opened_for_read         : 1; // opened_for_read and
 114
 115         unsigned int opened_for_write        : 1; // opened_for_write can
 116                                                   // be set simultaneously
 117
 118         unsigned int binary                  : 1; // opened for binary or
 119                                                   // text mode?
 120
 121 #ifdef CYGFUN_LIBC_STDIO_ungetc
 122         unsigned int unread_char_buf_in_use  : 1; // unget buf in use?
 123 #endif
 124
 125 #ifdef CYGSEM_LIBC_STDIO_WANT_BUFFERED_IO
 126         unsigned int buffering               : 1; // Is this file buffered?
 127
 128         unsigned int line_buffering          : 1; // If so, is it line
 129                                                   // buffered? If it is
 130                                                   // buffered, but NOT line
 131                                                   // buffered, it must be
 132                                                   // fully buffered
 133
 134         unsigned int last_buffer_op_was_read : 1; // did we last read from
 135                                                   // the buffer. If not we
 136                                                   // must have written
 137 #endif
 138         unsigned int readbuf_char_in_use     : 1; // is the above
 139                                                   // readbuf_char in use?
 140
 141     } flags;
 142
 143     // current position for reading/writing
 144     fpos_t position;
 145
 146 #ifdef CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS
 147     Cyg_Mutex stream_lock;  // used for locking this stream
 148 #endif // ifdef CYGSEM_LIBC_STDIO_THREAD_SAFE_STREAMS
 149
 150 #ifdef CYGDBG_USE_ASSERTS
 151     // a value to check that this class is hopefully valid
 152     cyg_ucount32 magic_validity_word;
 153 #endif
 154
 155 public:
 156     // different modes when constructing (i.e. opening).
 157     typedef enum {
 158         CYG_STREAM_READ,
 159         CYG_STREAM_WRITE,
 160         CYG_STREAM_READWRITE_NOCREATE,
 161         CYG_STREAM_READWRITE_CREATE
 162     } OpenMode;
 163
 164     // CONSTRUCTORS
 165
 166     // This constructs the stream - effectively opens the file. This is
 167     // used for static initialisation, and actually calls construct below
 168     //
 169     // dev is a valid Cyg_Device_Table_t, although it does not have to
 170     // be a member of the device table object itself
 171     //
 172     // open_mode is one of CYG_STREAM_READ, CYG_STREAM_WRITE,
 173     // CYG_STREAM_READWRITE_NOCREATE or CYG_STREAM_READWRITE_CREATE
 174     //
 175     // append is true if the file position should be set at EOF on opening
 176     //
 177     // binary is true if this is a binary stream. Otherwise it is a text
 178     // stream and character conversions (especially newline) may occur
 179     //
 180     // buffer_mode is one of _IONBF, _IOLBF, _IOFBF (from <stdio.h>)
 181     // If buffer_mode is _IONBF, buffer_size should still be set to 0
 182     // and buffer_addr to NULL. If buffering is not configured, none
 183     // of buffer_mode, buffer_size and buffer_addr have any effect
 184     //
 185     // buffer_size is the size of buffer to use
 186     //
 187     // buffer_addr is the address of a user supplied buffer. By default
 188     // (when NULL) a system one is provided.
 189     //
 190     // The "return code" is set by assignment to the error member of this
 191     // stream - use the get_error() method to check
 192
 193     Cyg_StdioStream( cyg_stdio_handle_t dev, OpenMode open_mode,
 194                      cyg_bool append, cyg_bool binary, int buffer_mode,
 195                      cyg_ucount32 buffer_size=BUFSIZ,
 196                      cyg_uint8 *buffer_addr=NULL );
 197
 198     Cyg_StdioStream( OpenMode open_mode,
 199                      cyg_ucount32 buffer_size=BUFSIZ,
 200                      cyg_uint8 *buffer_addr=NULL );
 201
 202 private:
 203     void initialize( cyg_stdio_handle_t dev, OpenMode open_mode,
 204                      cyg_bool append, cyg_bool binary, int buffer_mode,
 205                      cyg_ucount32 buffer_size=BUFSIZ,
 206                      cyg_uint8 *buffer_addr=NULL );
 207 public:
 208
 209     // DESTRUCTOR
 210
 211     ~Cyg_StdioStream();
 212
 213
 214     // MEMBER FUNCTIONS
 215
 216     // Close the stream. This should be called before the destructor,
 217     // so we can see and report any errors produced.
 218     Cyg_ErrNo close();
 219
 220     // Refill read buffer from the stream - note this blocks until
 221     // something arrives on the stream
 222     Cyg_ErrNo
 223     refill_read_buffer( void );
 224
 225
 226     // Read not more than buffer_length bytes from the read buffer into the
 227     // user buffer.
 228     // The number of bytes put into the user buffer is written
 229     // into *bytes_read
 230     Cyg_ErrNo
 231     read( cyg_uint8 *user_buffer, cyg_ucount32 buffer_length,
 232           cyg_ucount32 *bytes_read );
 233
 234
 235     // Read a single byte from the stream. Returns EAGAIN if no character
 236     // available or EEOF if end of file (as well as setting the EOF state)
 237     Cyg_ErrNo
 238     read_byte( cyg_uint8 *c );
 239
 240     // Read a single byte from the stream, but don't remove it. Returns
 241     // EAGAIN if no character available or EEOF if end of file (as well
 242     // as setting the EOF state)
 243     Cyg_ErrNo
 244     peek_byte( cyg_uint8 *c );
 245
 246
 247     // Return a byte into the stream - basically the same as ungetc()
 248     Cyg_ErrNo
 249     unread_byte( cyg_uint8 c );
 250
 251     // the number of bytes available to read without needing to refill the
 252     // buffer
 253     cyg_ucount32
 254     bytes_available_to_read( void );
 255
 256     Cyg_ErrNo
 257     write( const cyg_uint8 *buffer, cyg_ucount32 buffer_length,
 258            cyg_ucount32 *bytes_written );
 259
 260     Cyg_ErrNo
 261     write_byte( cyg_uint8 c );
 262
 263
 264     Cyg_ErrNo
 265     flush_output( void );
 266
 267     Cyg_ErrNo
 268     flush_output_unlocked( void );
 269
 270     // prevent multiple access in thread safe mode
 271
 272     // lock_me() returns false if it couldn't be locked, which could
 273     // happen if the file descriptor is bad
 274
 275     cyg_bool
 276     lock_me( void );
 277
 278     // trylock_me() returns false if it couldn't be locked, probably
 279     // because it is already locked
 280     cyg_bool
 281     trylock_me( void );
 282
 283     void
 284     unlock_me( void );
 285
 286     // get error status for this file
 287     Cyg_ErrNo
 288     get_error( void );
 289
 290     // set error status for this file.
 291     void
 292     set_error( Cyg_ErrNo errno_to_set );
 293
 294     // are we at EOF? true means we are, false means no
 295     cyg_bool
 296     get_eof_state( void );
 297
 298     // Set whether we are at EOF.
 299     void
 300     set_eof_state( cyg_bool eof_to_set );
 301
 302     // retrieve position
 303     Cyg_ErrNo
 304     get_position( fpos_t *pos );
 305
 306     // set absolute position. whence is SEEK_SET, SEEK_CUR, or SEEK_END
 307     Cyg_ErrNo
 308     set_position( fpos_t pos, int whence );
 309
 310     // Return my_device
 311     cyg_stdio_handle_t get_dev() { return my_device; };
 312
 313     CYGDBG_DEFINE_CHECK_THIS
 314 };
 315
 316 // INLINE FUNCTIONS
 317
 318 #include <cyg/libc/stdio/stream.inl>
 319
 320 #endif // CYGONCE_LIBC_STDIO_STREAM_HXX multiple inclusion protection
 321
 322 // EOF stream.hxx