vcs-svn/line_buffer.txt

   1 line_buffer API
   2 ===============
   3
   4 The line_buffer library provides a convenient interface for
   5 mostly-line-oriented input.
   6
   7 Each line is not permitted to exceed 10000 bytes.  The provided
   8 functions are not thread-safe or async-signal-safe, and like
   9 `fgets()`, they generally do not function correctly if interrupted
  10 by a signal without SA_RESTART set.
  11
  12 Calling sequence
  13 ----------------
  14
  15 The calling program:
  16
  17  - initializes a `struct line_buffer` to LINE_BUFFER_INIT
  18  - specifies a file to read with `buffer_init`
  19  - processes input with `buffer_read_line`, `buffer_read_string`,
  20    `buffer_skip_bytes`, and `buffer_copy_bytes`
  21  - closes the file with `buffer_deinit`, perhaps to start over and
  22    read another file.
  23
  24 When finished, the caller can use `buffer_reset` to deallocate
  25 resources.
  26
  27 Using temporary files
  28 ---------------------
  29
  30 Temporary files provide a place to store data that should not outlive
  31 the calling program.  A program
  32
  33  - initializes a `struct line_buffer` to LINE_BUFFER_INIT
  34  - requests a temporary file with `buffer_tmpfile_init`
  35  - acquires an output handle by calling `buffer_tmpfile_rewind`
  36  - uses standard I/O functions like `fprintf` and `fwrite` to fill
  37    the temporary file
  38  - declares writing is over with `buffer_tmpfile_prepare_to_read`
  39  - can re-read what was written with `buffer_read_line`,
  40    `buffer_read_string`, and so on
  41  - can reuse the temporary file by calling `buffer_tmpfile_rewind`
  42    again
  43  - removes the temporary file with `buffer_deinit`, perhaps to
  44    reuse the line_buffer for some other file.
  45
  46 When finished, the calling program can use `buffer_reset` to deallocate
  47 resources.
  48
  49 Functions
  50 ---------
  51
  52 `buffer_init`, `buffer_fdinit`::
  53         Open the named file or file descriptor for input.
  54         buffer_init(buf, NULL) prepares to read from stdin.
  55         On failure, returns -1 (with errno indicating the nature
  56         of the failure).
  57
  58 `buffer_deinit`::
  59         Stop reading from the current file (closing it unless
  60         it was stdin).  Returns nonzero if `fclose` fails or
  61         the error indicator was set.
  62
  63 `buffer_read_line`::
  64         Read a line and strip off the trailing newline.
  65         On failure or end of file, returns NULL.
  66
  67 `buffer_read_string`::
  68         Read `len` characters of input or up to the end of the
  69         file, whichever comes first.  Returns NULL on error.
  70         Returns whatever characters were read (possibly "")
  71         for end of file.
  72
  73 `buffer_copy_bytes`::
  74         Read `len` bytes of input and dump them to the standard output
  75         stream.  Returns early for error or end of file.
  76
  77 `buffer_skip_bytes`::
  78         Discards `len` bytes from the input stream (stopping early
  79         if necessary because of an error or eof).  Return value is
  80         the number of bytes successfully read.
  81
  82 `buffer_reset`::
  83         Deallocates non-static buffers.