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,
   7  *   2006, 2008, 2009, 2010, 2011, 2012 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 <stdio.h>
  30 #include <string.h>
  31 #include <unistd.h>
  32 #include "libguile/gc.h"
  33 #include "libguile/tags.h"
  34 #include "libguile/error.h"
  35 #include "libguile/print.h"
  36 #include "libguile/struct.h"
  37 #include "libguile/threads.h"
  38 #include "libguile/strings.h"
  39
  40 \f
  41
  42 #define SCM_INITIAL_PUTBACK_BUF_SIZE 4
  43
  44 /* values for the rw_active flag.  */
  45 typedef enum scm_t_port_rw_active {
  46   SCM_PORT_NEITHER = 0,
  47   SCM_PORT_READ = 1,
  48   SCM_PORT_WRITE = 2
  49 } scm_t_port_rw_active;
  50
  51 typedef enum scm_t_port_encoding_mode {
  52   SCM_PORT_ENCODING_MODE_UTF8,
  53   SCM_PORT_ENCODING_MODE_LATIN1,
  54   SCM_PORT_ENCODING_MODE_ICONV
  55 } scm_t_port_encoding_mode;
  56
  57 /* This is a separate object so that only those ports that use iconv
  58    cause finalizers to be registered.  */
  59 typedef struct scm_t_iconv_descriptors
  60 {
  61   /* input/output iconv conversion descriptors */
  62   void *input_cd;
  63   void *output_cd;
  64 } scm_t_iconv_descriptors;
  65
  66 /* C representation of a Scheme port.  */
  67
  68 typedef struct
  69 {
  70   SCM port;                     /* Link back to the port object.  */
  71   scm_i_pthread_mutex_t *lock;  /* A recursive lock for this port.  */
  72
  73   /* data for the underlying port implementation as a raw C value. */
  74   scm_t_bits stream;
  75
  76   SCM file_name;                /* debugging support.  */
  77   long line_number;             /* debugging support.  */
  78   int column_number;            /* debugging support.  */
  79
  80   /* port buffers.  the buffer(s) are set up for all ports.
  81      in the case of string ports, the buffer is the string itself.
  82      in the case of unbuffered file ports, the buffer is a
  83      single char: shortbuf.  */
  84
  85   /* this buffer is filled from read_buf to read_end using the ptob
  86      buffer_fill.  then input requests are taken from read_pos until
  87      it reaches read_end.  */
  88
  89   unsigned char *read_buf;      /* buffer start.  */
  90   const unsigned char *read_pos;/* the next unread char.  */
  91   unsigned char *read_end;      /* pointer to last buffered char + 1.  */
  92   scm_t_off read_buf_size;              /* size of the buffer.  */
  93
  94   /* when chars are put back into the buffer, e.g., using peek-char or
  95      unread-string, the read-buffer pointers are switched to cbuf.
  96      the original pointers are saved here and restored when the put-back
  97      chars have been consumed.  */
  98   unsigned char *saved_read_buf;
  99   const unsigned char *saved_read_pos;
 100   unsigned char *saved_read_end;
 101   scm_t_off saved_read_buf_size;
 102
 103   /* write requests are saved into this buffer at write_pos until it
 104      reaches write_buf + write_buf_size, then the ptob flush is
 105      called.  */
 106
 107   unsigned char *write_buf;     /* buffer start.  */
 108   unsigned char *write_pos;     /* pointer to last buffered char + 1.  */
 109   unsigned char *write_end;     /* pointer to end of buffer + 1.  */
 110   scm_t_off write_buf_size;             /* size of the buffer.  */
 111
 112   unsigned char shortbuf;       /* buffer for "unbuffered" streams.  */
 113
 114   int rw_random;                /* true if the port is random access.
 115                                    implies that the buffers must be
 116                                    flushed before switching between
 117                                    reading and writing, seeking, etc.  */
 118
 119   scm_t_port_rw_active rw_active; /* for random access ports,
 120                                      indicates which of the buffers
 121                                      is currently in use.  can be
 122                                      SCM_PORT_WRITE, SCM_PORT_READ,
 123                                      or SCM_PORT_NEITHER.  */
 124
 125
 126   /* a buffer for un-read chars and strings.  */
 127   unsigned char *putback_buf;
 128   size_t putback_buf_size;        /* allocated size of putback_buf.  */
 129
 130   /* Character encoding support  */
 131   char *encoding;
 132   scm_t_port_encoding_mode encoding_mode;
 133   scm_t_string_failed_conversion_handler ilseq_handler;
 134   scm_t_iconv_descriptors *iconv_descriptors;
 135 } scm_t_port;
 136
 137
 138 SCM_INTERNAL SCM scm_i_port_weak_set;
 139
 140
 141 #define SCM_READ_BUFFER_EMPTY_P(c_port) (c_port->read_pos >= c_port->read_end)
 142
 143 \f
 144
 145 #define SCM_EOF_OBJECT_P(x) (scm_is_eq ((x), SCM_EOF_VAL))
 146
 147 /* PORT FLAGS
 148  * A set of flags characterizes a port.
 149  * Note that we reserve the bits 1 << 24 and above for use by the
 150  * routines in the port's scm_ptobfuns structure.
 151  */
 152 #define SCM_OPN         (1L<<16) /* Is the port open? */
 153 #define SCM_RDNG        (2L<<16) /* Is it a readable port? */
 154 #define SCM_WRTNG       (4L<<16) /* Is it writable? */
 155 #define SCM_BUF0        (8L<<16) /* Is it unbuffered? */
 156 #define SCM_BUFLINE     (64L<<16) /* Is it line-buffered? */
 157
 158 #define SCM_PORTP(x) (SCM_HAS_TYP7 (x, scm_tc7_port))
 159 #define SCM_OPPORTP(x) (SCM_PORTP (x) && (SCM_CELL_WORD_0 (x) & SCM_OPN))
 160 #define SCM_INPUT_PORT_P(x) (SCM_PORTP (x) && (SCM_CELL_WORD_0 (x) & SCM_RDNG))
 161 #define SCM_OUTPUT_PORT_P(x) (SCM_PORTP (x) && (SCM_CELL_WORD_0 (x) & SCM_WRTNG))
 162 #define SCM_OPINPORTP(x) (SCM_OPPORTP (x) && SCM_INPUT_PORT_P (x))
 163 #define SCM_OPOUTPORTP(x) (SCM_OPPORTP (x) && SCM_OUTPUT_PORT_P (x))
 164 #define SCM_OPENP(x) (SCM_OPPORTP (x))
 165 #define SCM_CLOSEDP(x) (!SCM_OPENP (x))
 166 #define SCM_CLR_PORT_OPEN_FLAG(p) \
 167   SCM_SET_CELL_WORD_0 ((p), SCM_CELL_WORD_0 (p) & ~SCM_OPN)
 168
 169 #define SCM_PTAB_ENTRY(x)         ((scm_t_port *) SCM_CELL_WORD_1 (x))
 170 #define SCM_PORT_DESCRIPTOR(port) ((scm_t_ptob_descriptor *) SCM_CELL_WORD_2 (port))
 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
 179 #define SCM_INCLINE(port)       do {SCM_LINUM (port) += 1; SCM_COL (port) = 0;} while (0)
 180 #define SCM_ZEROCOL(port)       do {SCM_COL (port) = 0;} while (0)
 181 #define SCM_INCCOL(port)        do {SCM_COL (port) += 1;} while (0)
 182 #define SCM_DECCOL(port)        do {if (SCM_COL (port) > 0) SCM_COL (port) -= 1;} while (0)
 183 #define SCM_TABCOL(port)        do {SCM_COL (port) += 8 - SCM_COL (port) % 8;} while (0)
 184
 185 /* Maximum number of port types.  */
 186 #define SCM_I_MAX_PORT_TYPE_COUNT  256
 187
 188 \f
 189
 190 typedef enum scm_t_port_type_flags {
 191   SCM_PORT_TYPE_HAS_FLUSH = 1 << 0
 192 } scm_t_port_type_flags;
 193
 194 /* port-type description.  */
 195 typedef struct scm_t_ptob_descriptor
 196 {
 197   char *name;
 198   SCM (*mark) (SCM);
 199   size_t (*free) (SCM);
 200   int (*print) (SCM exp, SCM port, scm_print_state *pstate);
 201   SCM (*equalp) (SCM, SCM);
 202   int (*close) (SCM port);
 203
 204   void (*write) (SCM port, const void *data, size_t size);
 205   void (*flush) (SCM port);
 206
 207   void (*end_input) (SCM port, int offset);
 208   int (*fill_input) (SCM port);
 209   int (*input_waiting) (SCM port);
 210
 211   scm_t_off (*seek) (SCM port, scm_t_off OFFSET, int WHENCE);
 212   void (*truncate) (SCM port, scm_t_off length);
 213
 214   unsigned flags;
 215 } scm_t_ptob_descriptor;
 216
 217 #define SCM_TC2PTOBNUM(x) (0x0ff & ((x) >> 8))
 218 #define SCM_PTOBNUM(x) (SCM_TC2PTOBNUM (SCM_CELL_TYPE (x)))
 219 /* SCM_PTOBNAME can be 0 if name is missing */
 220 #define SCM_PTOBNAME(ptobnum) (scm_c_port_type_ref (ptobnum)->name)
 221
 222 /* Port types, and their vtables.  */
 223 SCM_INTERNAL long scm_c_num_port_types (void);
 224 SCM_API scm_t_ptob_descriptor* scm_c_port_type_ref (long ptobnum);
 225 SCM_API long scm_c_port_type_add_x (scm_t_ptob_descriptor *desc);
 226 SCM_API scm_t_bits scm_make_port_type (char *name,
 227                                        int (*fill_input) (SCM port),
 228                                        void (*write) (SCM port,
 229                                                       const void *data,
 230                                                       size_t size));
 231 SCM_API void scm_set_port_mark (scm_t_bits tc, SCM (*mark) (SCM));
 232 SCM_API void scm_set_port_free (scm_t_bits tc, size_t (*free) (SCM));
 233 SCM_API void scm_set_port_print (scm_t_bits tc,
 234                                  int (*print) (SCM exp,
 235                                                SCM port,
 236                                                scm_print_state *pstate));
 237 SCM_API void scm_set_port_equalp (scm_t_bits tc, SCM (*equalp) (SCM, SCM));
 238 SCM_API void scm_set_port_close (scm_t_bits tc, int (*close) (SCM));
 239
 240 SCM_API void scm_set_port_flush (scm_t_bits tc, void (*flush) (SCM port));
 241 SCM_API void scm_set_port_end_input (scm_t_bits tc,
 242                                      void (*end_input) (SCM port,
 243                                                         int offset));
 244 SCM_API void scm_set_port_seek (scm_t_bits tc,
 245                                 scm_t_off (*seek) (SCM port,
 246                                                    scm_t_off OFFSET,
 247                                                    int WHENCE));
 248 SCM_API void scm_set_port_truncate (scm_t_bits tc,
 249                                     void (*truncate) (SCM port,
 250                                                       scm_t_off length));
 251 SCM_API void scm_set_port_input_waiting (scm_t_bits tc, int (*input_waiting) (SCM));
 252
 253 /* The input, output, error, and load ports.  */
 254 SCM_API SCM scm_current_input_port (void);
 255 SCM_API SCM scm_current_output_port (void);
 256 SCM_API SCM scm_current_error_port (void);
 257 SCM_API SCM scm_current_warning_port (void);
 258 SCM_API SCM scm_current_load_port (void);
 259 SCM_API SCM scm_set_current_input_port (SCM port);
 260 SCM_API SCM scm_set_current_output_port (SCM port);
 261 SCM_API SCM scm_set_current_error_port (SCM port);
 262 SCM_API SCM scm_set_current_warning_port (SCM port);
 263 SCM_API void scm_dynwind_current_input_port (SCM port);
 264 SCM_API void scm_dynwind_current_output_port (SCM port);
 265 SCM_API void scm_dynwind_current_error_port (SCM port);
 266 SCM_INTERNAL void scm_i_dynwind_current_load_port (SCM port);
 267
 268 /* Mode bits.  */
 269 SCM_INTERNAL long scm_i_mode_bits (SCM modes);
 270 SCM_API long scm_mode_bits (char *modes);
 271 SCM_API SCM scm_port_mode (SCM port);
 272
 273 /* Low-level constructors.  */
 274 SCM_API SCM
 275 scm_c_make_port_with_encoding (scm_t_bits tag,
 276                                unsigned long mode_bits,
 277                                const char *encoding,
 278                                scm_t_string_failed_conversion_handler handler,
 279                                scm_t_bits stream);
 280 SCM_API SCM scm_c_make_port (scm_t_bits tag, unsigned long mode_bits,
 281                              scm_t_bits stream);
 282 SCM_API SCM scm_new_port_table_entry (scm_t_bits tag);
 283
 284 /* Predicates.  */
 285 SCM_API SCM scm_port_p (SCM x);
 286 SCM_API SCM scm_input_port_p (SCM x);
 287 SCM_API SCM scm_output_port_p (SCM x);
 288 SCM_API SCM scm_port_closed_p (SCM port);
 289 SCM_API SCM scm_eof_object_p (SCM x);
 290
 291 /* Closing ports.  */
 292 SCM_API SCM scm_close_port (SCM port);
 293 SCM_API SCM scm_close_input_port (SCM port);
 294 SCM_API SCM scm_close_output_port (SCM port);
 295
 296 /* Encoding characters to byte streams, and decoding byte streams to
 297    characters.  */
 298 SCM_INTERNAL const char *scm_i_default_port_encoding (void);
 299 SCM_INTERNAL void scm_i_set_default_port_encoding (const char *);
 300 SCM_INTERNAL scm_t_iconv_descriptors *scm_i_port_iconv_descriptors (SCM port);
 301 SCM_INTERNAL void scm_i_set_port_encoding_x (SCM port, const char *str);
 302 SCM_API SCM scm_port_encoding (SCM port);
 303 SCM_API SCM scm_set_port_encoding_x (SCM port, SCM encoding);
 304 SCM_INTERNAL scm_t_string_failed_conversion_handler scm_i_get_conversion_strategy (SCM port);
 305 SCM_INTERNAL void scm_i_set_conversion_strategy_x (SCM port,
 306                                                    scm_t_string_failed_conversion_handler h);
 307 SCM_API SCM scm_port_conversion_strategy (SCM port);
 308 SCM_API SCM scm_set_port_conversion_strategy_x (SCM port, SCM behavior);
 309
 310 /* Acquiring and releasing the port lock.  */
 311 SCM_API void scm_dynwind_lock_port (SCM port);
 312 SCM_INLINE int scm_c_lock_port (SCM port, scm_i_pthread_mutex_t **lock);
 313 SCM_INLINE int scm_c_try_lock_port (SCM port, scm_i_pthread_mutex_t **lock);
 314
 315 /* Input.  */
 316 SCM_API int scm_get_byte_or_eof (SCM port);
 317 SCM_INLINE int scm_get_byte_or_eof_unlocked (SCM port);
 318 SCM_API int scm_peek_byte_or_eof (SCM port);
 319 SCM_INLINE int scm_peek_byte_or_eof_unlocked (SCM port);
 320 SCM_API size_t scm_c_read (SCM port, void *buffer, size_t size);
 321 SCM_API size_t scm_c_read_unlocked (SCM port, void *buffer, size_t size);
 322 SCM_API scm_t_wchar scm_getc (SCM port);
 323 SCM_API scm_t_wchar scm_getc_unlocked (SCM port);
 324 SCM_API SCM scm_read_char (SCM port);
 325
 326 /* Pushback.  */
 327 SCM_INTERNAL void scm_unget_byte (int c, SCM port);
 328 SCM_INTERNAL void scm_unget_byte_unlocked (int c, SCM port);
 329 SCM_API void scm_ungetc (scm_t_wchar c, SCM port);
 330 SCM_API void scm_ungetc_unlocked (scm_t_wchar c, SCM port);
 331 SCM_API void scm_ungets (const char *s, int n, SCM port);
 332 SCM_API void scm_ungets_unlocked (const char *s, int n, SCM port);
 333 SCM_API SCM scm_peek_char (SCM port);
 334 SCM_API SCM scm_unread_char (SCM cobj, SCM port);
 335 SCM_API SCM scm_unread_string (SCM str, SCM port);
 336
 337 /* Manipulating the buffers.  */
 338 SCM_API void scm_port_non_buffer (scm_t_port *pt);
 339 SCM_API int scm_fill_input (SCM port);
 340 SCM_API int scm_fill_input_unlocked (SCM port);
 341 SCM_INTERNAL size_t scm_take_from_input_buffers (SCM port, char *dest, size_t read_len);
 342 SCM_API SCM scm_drain_input (SCM port);
 343 SCM_API void scm_end_input (SCM port);
 344 SCM_API void scm_end_input_unlocked (SCM port);
 345 SCM_API SCM scm_force_output (SCM port);
 346 SCM_API void scm_flush (SCM port);
 347 SCM_API void scm_flush_unlocked (SCM port);
 348
 349 /* Output.  */
 350 SCM_API void scm_putc (char c, SCM port);
 351 SCM_INLINE void scm_putc_unlocked (char c, SCM port);
 352 SCM_API void scm_puts (const char *str_data, SCM port);
 353 SCM_INLINE void scm_puts_unlocked (const char *str_data, SCM port);
 354 SCM_API void scm_c_write (SCM port, const void *buffer, size_t size);
 355 SCM_API void scm_c_write_unlocked (SCM port, const void *buffer, size_t size);
 356 SCM_API void scm_lfwrite (const char *ptr, size_t size, SCM port);
 357 SCM_API void scm_lfwrite_unlocked (const char *ptr, size_t size, SCM port);
 358 SCM_INTERNAL void scm_lfwrite_substr (SCM str, size_t start, size_t end,
 359                                       SCM port);
 360
 361 /* Querying and setting positions, and character availability.  */
 362 SCM_API SCM scm_char_ready_p (SCM port);
 363 SCM_API SCM scm_seek (SCM object, SCM offset, SCM whence);
 364 SCM_API SCM scm_truncate_file (SCM object, SCM length);
 365 SCM_API SCM scm_port_line (SCM port);
 366 SCM_API SCM scm_set_port_line_x (SCM port, SCM line);
 367 SCM_API SCM scm_port_column (SCM port);
 368 SCM_API SCM scm_set_port_column_x (SCM port, SCM line);
 369 SCM_API SCM scm_port_filename (SCM port);
 370 SCM_API SCM scm_set_port_filename_x (SCM port, SCM filename);
 371
 372 /* Implementation helpers for port printing functions.  */
 373 SCM_API int scm_port_print (SCM exp, SCM port, scm_print_state *);
 374 SCM_API void scm_print_port_mode (SCM exp, SCM port);
 375
 376 /* Iterating over all ports.  */
 377 SCM_API SCM scm_port_for_each (SCM proc);
 378 SCM_API void scm_c_port_for_each (void (*proc)(void *data, SCM p), void *data);
 379 SCM_API SCM scm_flush_all_ports (void);
 380
 381 /* Void ports.  */
 382 SCM_API SCM scm_void_port (char * mode_str);
 383 SCM_API SCM scm_sys_make_void_port (SCM mode);
 384
 385 /* Initialization.  */
 386 SCM_INTERNAL void scm_init_ports (void);
 387
 388
 389 /* Inline function implementations.  */
 390
 391 #if SCM_CAN_INLINE || defined SCM_INLINE_C_IMPLEMENTING_INLINES
 392 SCM_INLINE_IMPLEMENTATION int
 393 scm_c_lock_port (SCM port, scm_i_pthread_mutex_t **lock)
 394 {
 395   *lock = SCM_PTAB_ENTRY (port)->lock;
 396
 397   if (*lock)
 398     return scm_i_pthread_mutex_lock (*lock);
 399   else
 400     return 0;
 401 }
 402
 403 SCM_INLINE_IMPLEMENTATION int
 404 scm_c_try_lock_port (SCM port, scm_i_pthread_mutex_t **lock)
 405 {
 406   *lock = SCM_PTAB_ENTRY (port)->lock;
 407   if (*lock)
 408     {
 409       int ret = scm_i_pthread_mutex_trylock (*lock);
 410       if (ret != 0)
 411         *lock = NULL;
 412       return ret;
 413     }
 414   else
 415     return 0;
 416 }
 417
 418 SCM_INLINE_IMPLEMENTATION int
 419 scm_get_byte_or_eof_unlocked (SCM port)
 420 {
 421   int c;
 422   scm_t_port *pt = SCM_PTAB_ENTRY (port);
 423
 424   if (pt->rw_active == SCM_PORT_WRITE)
 425     /* may be marginally faster than calling scm_flush.  */
 426     SCM_PORT_DESCRIPTOR (port)->flush (port);
 427
 428   if (pt->rw_random)
 429     pt->rw_active = SCM_PORT_READ;
 430
 431   if (pt->read_pos >= pt->read_end)
 432     {
 433       if (SCM_UNLIKELY (scm_fill_input_unlocked (port) == EOF))
 434         return EOF;
 435     }
 436
 437   c = *(pt->read_pos++);
 438
 439   return c;
 440 }
 441
 442 /* Like `scm_get_byte_or_eof' but does not change PORT's `read_pos'.  */
 443 SCM_INLINE_IMPLEMENTATION int
 444 scm_peek_byte_or_eof_unlocked (SCM port)
 445 {
 446   int c;
 447   scm_t_port *pt = SCM_PTAB_ENTRY (port);
 448
 449   if (pt->rw_active == SCM_PORT_WRITE)
 450     /* may be marginally faster than calling scm_flush.  */
 451     SCM_PORT_DESCRIPTOR (port)->flush (port);
 452
 453   if (pt->rw_random)
 454     pt->rw_active = SCM_PORT_READ;
 455
 456   if (pt->read_pos >= pt->read_end)
 457     {
 458       if (SCM_UNLIKELY (scm_fill_input_unlocked (port) == EOF))
 459         return EOF;
 460     }
 461
 462   c = *pt->read_pos;
 463
 464   return c;
 465 }
 466
 467 SCM_INLINE_IMPLEMENTATION void
 468 scm_putc_unlocked (char c, SCM port)
 469 {
 470   SCM_ASSERT_TYPE (SCM_OPOUTPORTP (port), port, 0, NULL, "output port");
 471   scm_lfwrite_unlocked (&c, 1, port);
 472 }
 473
 474 SCM_INLINE_IMPLEMENTATION void
 475 scm_puts_unlocked (const char *s, SCM port)
 476 {
 477   SCM_ASSERT_TYPE (SCM_OPOUTPORTP (port), port, 0, NULL, "output port");
 478   scm_lfwrite_unlocked (s, strlen (s), port);
 479 }
 480 #endif  /* SCM_CAN_INLINE || defined SCM_INLINE_C_IMPLEMENTING_INLINES */
 481
 482 #endif  /* SCM_PORTS_H */
 483
 484 /*
 485   Local Variables:
 486   c-file-style: "gnu"
 487   End:
 488 */