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