libguile/ports.h

   1 /* classes: h_files */
   2
   3 #ifndef SCM_PORTS_H
   4 #define SCM_PORTS_H
   5
   6 /* Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2003, 2004, 2006,
   7  *   2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
   8  *
   9  * This library is free software; you can redistribute it and/or
  10  * modify it under the terms of the GNU Lesser General Public License
  11  * as published by the Free Software Foundation; either version 3 of
  12  * the License, or (at your option) any later version.
  13  *
  14  * This library is distributed in the hope that it will be useful, but
  15  * WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17  * Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public
  20  * License along with this library; if not, write to the Free Software
  21  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  22  * 02110-1301 USA
  23  */
  24
  25 \f
  26
  27 #include "libguile/__scm.h"
  28
  29 #include <unistd.h>
  30 #include "libguile/print.h"
  31 #include "libguile/struct.h"
  32 #include "libguile/threads.h"
  33 #include "libguile/strings.h"
  34
  35 \f
  36
  37 #define SCM_INITIAL_PUTBACK_BUF_SIZE 4
  38
  39 /* values for the rw_active flag.  */
  40 typedef enum scm_t_port_rw_active {
  41   SCM_PORT_NEITHER = 0,
  42   SCM_PORT_READ = 1,
  43   SCM_PORT_WRITE = 2
  44 } scm_t_port_rw_active;
  45
  46 /* C representation of a Scheme port.  */
  47
  48 typedef struct
  49 {
  50   SCM port;                     /* Link back to the port object.  */
  51   int revealed;                 /* 0 not revealed, > 1 revealed.
  52                                  * Revealed ports do not get GC'd.
  53                                  */
  54   /* data for the underlying port implementation as a raw C value. */
  55   scm_t_bits stream;
  56
  57   SCM file_name;                /* debugging support.  */
  58   long line_number;             /* debugging support.  */
  59   int column_number;            /* debugging support.  */
  60
  61   /* Character encoding support  */
  62   char *encoding;
  63   scm_t_string_failed_conversion_handler ilseq_handler;
  64
  65   /* port buffers.  the buffer(s) are set up for all ports.
  66      in the case of string ports, the buffer is the string itself.
  67      in the case of unbuffered file ports, the buffer is a
  68      single char: shortbuf.  */
  69
  70   /* this buffer is filled from read_buf to read_end using the ptob
  71      buffer_fill.  then input requests are taken from read_pos until
  72      it reaches read_end.  */
  73
  74   unsigned char *read_buf;      /* buffer start.  */
  75   const unsigned char *read_pos;/* the next unread char.  */
  76   unsigned char *read_end;      /* pointer to last buffered char + 1.  */
  77   scm_t_off read_buf_size;              /* size of the buffer.  */
  78
  79   /* when chars are put back into the buffer, e.g., using peek-char or
  80      unread-string, the read-buffer pointers are switched to cbuf.
  81      the original pointers are saved here and restored when the put-back
  82      chars have been consumed.  */
  83   unsigned char *saved_read_buf;
  84   const unsigned char *saved_read_pos;
  85   unsigned char *saved_read_end;
  86   scm_t_off saved_read_buf_size;
  87
  88   /* write requests are saved into this buffer at write_pos until it
  89      reaches write_buf + write_buf_size, then the ptob flush is
  90      called.  */
  91
  92   unsigned char *write_buf;     /* buffer start.  */
  93   unsigned char *write_pos;     /* pointer to last buffered char + 1.  */
  94   unsigned char *write_end;     /* pointer to end of buffer + 1.  */
  95   scm_t_off write_buf_size;             /* size of the buffer.  */
  96
  97   unsigned char shortbuf;       /* buffer for "unbuffered" streams.  */
  98
  99   int rw_random;                /* true if the port is random access.
 100                                    implies that the buffers must be
 101                                    flushed before switching between
 102                                    reading and writing, seeking, etc.  */
 103
 104   scm_t_port_rw_active rw_active; /* for random access ports,
 105                                      indicates which of the buffers
 106                                      is currently in use.  can be
 107                                      SCM_PORT_WRITE, SCM_PORT_READ,
 108                                      or SCM_PORT_NEITHER.  */
 109
 110
 111   /* a buffer for un-read chars and strings.  */
 112   unsigned char *putback_buf;
 113   size_t putback_buf_size;        /* allocated size of putback_buf.  */
 114
 115   /* IMPORTANT: 'input_cd' and 'output_cd' used to be pointers to the
 116      input and output iconv descriptors, but those have been moved to
 117      the internal-only port structure defined in ports-internal.h.
 118
 119      Given that we must preserve ABI compatibility in 2.0, we cannot
 120      safely change this public structure without running afoul of C
 121      strict aliasing rules.  We cannot even change the member names.
 122
 123      To work around this, in this public structure, 'input_cd' has been
 124      repurposed to be a pointer to the internal port structure (see
 125      ports-internal.h), and 'output_cd' is now unused.
 126
 127      This will be cleaned up in 2.2.  */
 128
 129   void *input_cd;   /* XXX actually a pointer to scm_t_port_internal */
 130   void *output_cd;  /* XXX actually unused */
 131 } scm_t_port;
 132
 133
 134 SCM_INTERNAL scm_i_pthread_mutex_t scm_i_port_table_mutex;
 135 SCM_INTERNAL SCM scm_i_port_weak_hash;
 136
 137
 138 #define SCM_READ_BUFFER_EMPTY_P(c_port) (c_port->read_pos >= c_port->read_end)
 139
 140 \f
 141
 142 #define SCM_EOF_OBJECT_P(x) (scm_is_eq ((x), SCM_EOF_VAL))
 143
 144 /* PORT FLAGS
 145  * A set of flags characterizes a port.
 146  * Note that we reserve the bits 1 << 24 and above for use by the
 147  * routines in the port's scm_ptobfuns structure.
 148  */
 149 #define SCM_OPN         (1L<<16) /* Is the port open? */
 150 #define SCM_RDNG        (2L<<16) /* Is it a readable port? */
 151 #define SCM_WRTNG       (4L<<16) /* Is it writable? */
 152 #define SCM_BUF0        (8L<<16) /* Is it unbuffered? */
 153 #define SCM_BUFLINE     (64L<<16) /* Is it line-buffered? */
 154
 155 #define SCM_PORTP(x) (!SCM_IMP (x) && (SCM_TYP7 (x) == scm_tc7_port))
 156 #define SCM_OPPORTP(x) (!SCM_IMP(x) && (((0x7f | SCM_OPN) & SCM_CELL_WORD_0(x))==(scm_tc7_port | SCM_OPN)))
 157 #define SCM_OPINPORTP(x) (!SCM_IMP(x) && (((0x7f | SCM_OPN | SCM_RDNG) & SCM_CELL_WORD_0(x))==(scm_tc7_port | SCM_OPN | SCM_RDNG)))
 158 #define SCM_OPOUTPORTP(x) (!SCM_IMP(x) && (((0x7f | SCM_OPN | SCM_WRTNG) & SCM_CELL_WORD_0(x))==(scm_tc7_port | SCM_OPN | SCM_WRTNG)))
 159 #define SCM_INPUT_PORT_P(x) \
 160   (!SCM_IMP(x) \
 161    && (((0x7f | SCM_RDNG) & SCM_CELL_WORD_0(x)) == (scm_tc7_port | SCM_RDNG)))
 162 #define SCM_OUTPUT_PORT_P(x) \
 163   (!SCM_IMP(x) \
 164    && (((0x7f | SCM_WRTNG) & SCM_CELL_WORD_0(x))==(scm_tc7_port | SCM_WRTNG)))
 165 #define SCM_OPENP(x) (!SCM_IMP(x) && (SCM_OPN & SCM_CELL_WORD_0 (x)))
 166 #define SCM_CLOSEDP(x) (!SCM_OPENP(x))
 167 #define SCM_CLR_PORT_OPEN_FLAG(p) \
 168   SCM_SET_CELL_WORD_0 ((p), SCM_CELL_WORD_0 (p) & ~SCM_OPN)
 169
 170 #define SCM_PTAB_ENTRY(x)         ((scm_t_port *) SCM_CELL_WORD_1 (x))
 171 #define SCM_SETPTAB_ENTRY(x, ent)  (SCM_SET_CELL_WORD_1 ((x), (scm_t_bits) (ent)))
 172 #define SCM_STREAM(x)             (SCM_PTAB_ENTRY(x)->stream)
 173 #define SCM_SETSTREAM(x, s)        (SCM_PTAB_ENTRY(x)->stream = (scm_t_bits) (s))
 174 #define SCM_FILENAME(x)           (SCM_PTAB_ENTRY(x)->file_name)
 175 #define SCM_SET_FILENAME(x, n)    (SCM_PTAB_ENTRY(x)->file_name = (n))
 176 #define SCM_LINUM(x)              (SCM_PTAB_ENTRY(x)->line_number)
 177 #define SCM_COL(x)                (SCM_PTAB_ENTRY(x)->column_number)
 178 #define SCM_REVEALED(x)           (SCM_PTAB_ENTRY(x)->revealed)
 179 #define SCM_SETREVEALED(x, s)      (SCM_PTAB_ENTRY(x)->revealed = (s))
 180
 181 #define SCM_INCLINE(port)       do {SCM_LINUM (port) += 1; SCM_COL (port) = 0;} while (0)
 182 #define SCM_ZEROCOL(port)       do {SCM_COL (port) = 0;} while (0)
 183 #define SCM_INCCOL(port)        do {SCM_COL (port) += 1;} while (0)
 184 #define SCM_DECCOL(port)        do {if (SCM_COL (port) > 0) SCM_COL (port) -= 1;} while (0)
 185 #define SCM_TABCOL(port)        do {SCM_COL (port) += 8 - SCM_COL (port) % 8;} while (0)
 186
 187 /* Maximum number of port types.  */
 188 #define SCM_I_MAX_PORT_TYPE_COUNT  256
 189
 190 \f
 191
 192 /* port-type description.  */
 193 typedef struct scm_t_ptob_descriptor
 194 {
 195   char *name;
 196   SCM (*mark) (SCM);
 197   size_t (*free) (SCM);
 198   int (*print) (SCM exp, SCM port, scm_print_state *pstate);
 199   SCM (*equalp) (SCM, SCM);
 200   int (*close) (SCM port);
 201
 202   void (*write) (SCM port, const void *data, size_t size);
 203   void (*flush) (SCM port);
 204
 205   void (*end_input) (SCM port, int offset);
 206   int (*fill_input) (SCM port);
 207   int (*input_waiting) (SCM port);
 208
 209   scm_t_off (*seek) (SCM port, scm_t_off OFFSET, int WHENCE);
 210   void (*truncate) (SCM port, scm_t_off length);
 211
 212 } scm_t_ptob_descriptor;
 213
 214 #define SCM_TC2PTOBNUM(x) (0x0ff & ((x) >> 8))
 215 #define SCM_PTOBNUM(x) (SCM_TC2PTOBNUM (SCM_CELL_TYPE (x)))
 216 /* SCM_PTOBNAME can be 0 if name is missing */
 217 #define SCM_PTOBNAME(ptobnum) scm_ptobs[ptobnum].name
 218
 219 \f
 220
 221 /* Hey you!  Yes you, reading the header file!  We're going to deprecate
 222    scm_ptobs in 2.2, so please don't write any new code that uses it.
 223    Thanks.  */
 224 SCM_API scm_t_ptob_descriptor *scm_ptobs;
 225 SCM_API long scm_numptob;
 226
 227 \f
 228
 229 SCM_API SCM scm_markstream (SCM ptr);
 230 SCM_API scm_t_bits scm_make_port_type (char *name,
 231                                        int (*fill_input) (SCM port),
 232                                        void (*write) (SCM port,
 233                                                       const void *data,
 234                                                       size_t size));
 235 SCM_API void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM));
 236 SCM_API void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM));
 237 SCM_API void scm_set_port_print (scm_t_bits tc,
 238                                  int (*print) (SCM exp,
 239                                                SCM port,
 240                                                scm_print_state *pstate));
 241 SCM_API void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM));
 242 SCM_API void scm_set_port_close (scm_t_bits tc, int (*close) (SCM));
 243
 244 SCM_API void scm_set_port_flush (scm_t_bits tc,
 245                                  void (*flush) (SCM port));
 246 SCM_API void scm_set_port_end_input (scm_t_bits tc,
 247                                      void (*end_input) (SCM port,
 248                                                         int offset));
 249 SCM_API void scm_set_port_seek (scm_t_bits tc,
 250                                 scm_t_off (*seek) (SCM port,
 251                                                    scm_t_off OFFSET,
 252                                                    int WHENCE));
 253 SCM_API void scm_set_port_truncate (scm_t_bits tc,
 254                                     void (*truncate) (SCM port,
 255                                                       scm_t_off length));
 256 SCM_API void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM));
 257 SCM_API SCM scm_char_ready_p (SCM port);
 258 SCM_API size_t scm_take_from_input_buffers (SCM port, char *dest,
 259                                             size_t read_len);
 260 SCM_API SCM scm_drain_input (SCM port);
 261 SCM_API SCM scm_current_input_port (void);
 262 SCM_API SCM scm_current_output_port (void);
 263 SCM_API SCM scm_current_error_port (void);
 264 SCM_API SCM scm_current_warning_port (void);
 265 SCM_API SCM scm_current_load_port (void);
 266 SCM_API SCM scm_set_current_input_port (SCM port);
 267 SCM_API SCM scm_set_current_output_port (SCM port);
 268 SCM_API SCM scm_set_current_error_port (SCM port);
 269 SCM_API SCM scm_set_current_warning_port (SCM port);
 270 SCM_API void scm_dynwind_current_input_port (SCM port);
 271 SCM_API void scm_dynwind_current_output_port (SCM port);
 272 SCM_API void scm_dynwind_current_error_port (SCM port);
 273 SCM_API SCM scm_new_port_table_entry (scm_t_bits tag);
 274 SCM_API void scm_grow_port_cbuf (SCM port, size_t requested);
 275 SCM_API SCM scm_pt_size (void);
 276 SCM_API SCM scm_pt_member (SCM member);
 277 SCM_API void scm_port_non_buffer (scm_t_port *pt);
 278 SCM_API int scm_revealed_count (SCM port);
 279 SCM_API SCM scm_port_revealed (SCM port);
 280 SCM_API SCM scm_set_port_revealed_x (SCM port, SCM rcount);
 281 SCM_API long scm_mode_bits (char *modes);
 282 SCM_API SCM scm_port_mode (SCM port);
 283 SCM_API SCM scm_close_input_port (SCM port);
 284 SCM_API SCM scm_close_output_port (SCM port);
 285 SCM_API SCM scm_close_port (SCM port);
 286 SCM_API SCM scm_port_for_each (SCM proc);
 287 SCM_API void scm_c_port_for_each (void (*proc)(void *data, SCM p), void *data);
 288 SCM_API SCM scm_input_port_p (SCM x);
 289 SCM_API SCM scm_output_port_p (SCM x);
 290 SCM_API SCM scm_port_p (SCM x);
 291 SCM_API SCM scm_port_closed_p (SCM port);
 292 SCM_API SCM scm_eof_object_p (SCM x);
 293 SCM_API SCM scm_force_output (SCM port);
 294 SCM_API SCM scm_flush_all_ports (void);
 295 SCM_API SCM scm_read_char (SCM port);
 296 SCM_API scm_t_wchar scm_getc (SCM port);
 297 SCM_API size_t scm_c_read (SCM port, void *buffer, size_t size);
 298 SCM_API void scm_c_write (SCM port, const void *buffer, size_t size);
 299 SCM_API void scm_lfwrite (const char *ptr, size_t size, SCM port);
 300 SCM_INTERNAL void scm_lfwrite_substr (SCM str, size_t start, size_t end,
 301                                       SCM port);
 302 SCM_API void scm_flush (SCM port);
 303 SCM_API void scm_end_input (SCM port);
 304 SCM_API int scm_fill_input (SCM port);
 305 SCM_API void scm_unget_bytes (const unsigned char *buf, size_t len, SCM port);
 306 SCM_API void scm_unget_byte (int c, SCM port);
 307 SCM_API void scm_ungetc (scm_t_wchar c, SCM port);
 308 SCM_API void scm_ungets (const char *s, int n, SCM port);
 309 SCM_API SCM scm_peek_char (SCM port);
 310 SCM_API SCM scm_unread_char (SCM cobj, SCM port);
 311 SCM_API SCM scm_unread_string (SCM str, SCM port);
 312 SCM_API SCM scm_seek (SCM object, SCM offset, SCM whence);
 313 SCM_API SCM scm_truncate_file (SCM object, SCM length);
 314 SCM_API SCM scm_port_line (SCM port);
 315 SCM_API SCM scm_set_port_line_x (SCM port, SCM line);
 316 SCM_API SCM scm_port_column (SCM port);
 317 SCM_API SCM scm_set_port_column_x (SCM port, SCM line);
 318 SCM_API SCM scm_port_filename (SCM port);
 319 SCM_API SCM scm_set_port_filename_x (SCM port, SCM filename);
 320 SCM_INTERNAL SCM scm_i_port_property (SCM port, SCM key);
 321 SCM_INTERNAL SCM scm_i_set_port_property_x (SCM port, SCM key, SCM value);
 322 SCM_INTERNAL const char *scm_i_default_port_encoding (void);
 323 SCM_INTERNAL void scm_i_set_default_port_encoding (const char *);
 324 SCM_INTERNAL void scm_i_set_port_encoding_x (SCM port, const char *str);
 325 SCM_API SCM scm_port_encoding (SCM port);
 326 SCM_API SCM scm_set_port_encoding_x (SCM port, SCM encoding);
 327 SCM_INTERNAL scm_t_string_failed_conversion_handler
 328 scm_i_default_port_conversion_handler (void);
 329 /* Use HANDLER as the default conversion strategy for future ports.  */
 330 SCM_INTERNAL void
 331 scm_i_set_default_port_conversion_handler (scm_t_string_failed_conversion_handler);
 332 SCM_API int scm_slow_get_byte_or_eof (SCM port);
 333 SCM_API int scm_slow_peek_byte_or_eof (SCM port);
 334
 335 SCM_API SCM scm_port_conversion_strategy (SCM port);
 336 SCM_API SCM scm_set_port_conversion_strategy_x (SCM port, SCM behavior);
 337 SCM_API int scm_port_print (SCM exp, SCM port, scm_print_state *);
 338 SCM_API void scm_print_port_mode (SCM exp, SCM port);
 339 SCM_API SCM scm_void_port (char * mode_str);
 340 SCM_API SCM scm_sys_make_void_port (SCM mode);
 341 SCM_INTERNAL void scm_init_ports (void);
 342
 343 #if SCM_ENABLE_DEPRECATED==1
 344 SCM_DEPRECATED scm_t_port * scm_add_to_port_table (SCM port);
 345 #endif
 346
 347 #ifdef GUILE_DEBUG
 348 SCM_API SCM scm_pt_size (void);
 349 SCM_API SCM scm_pt_member (SCM member);
 350 #endif /* GUILE_DEBUG */
 351
 352 /* internal */
 353
 354 SCM_INTERNAL long scm_i_mode_bits (SCM modes);
 355 SCM_INTERNAL void scm_i_dynwind_current_load_port (SCM port);
 356
 357
 358 #endif  /* SCM_PORTS_H */
 359
 360 /*
 361   Local Variables:
 362   c-file-style: "gnu"
 363   End:
 364 */