=head1	NAME

dkstream - generic interface to I/O operations

=head1	SYNOPSIS

  #include <dkstream.h>


  dk_stream_t *dkstream_new (void *data, dk_stream_fct_t *fct);
  
  size_t dkstream_write (dk_stream_t *s, char *b, size_t l);
  
  size_t dkstream_read  (dk_stream_t *s, char *b, size_t l);
  
  void  dkstream_delete (dk_stream_t *st);
  
  dk_stream_t *dkstream_openfile (
    char *name, char *mode, int ign, int *reason
  );
  
  dk_stream_t *dkstream_opengz (
    char *name, char *mode, int ign, int *reason
  );
  
  dk_stream_t *dkstream_openbz2 (
    char *name, char *mode, int ign, int *reason
  );
  
  char *dkstream_gets (
    dk_stream_t *st, char *buffer, size_t length
  );
  
  int dkstream_puts (dk_stream_t *st, char *buffer);
  
  void dkstream_close (dk_stream_t *st);
  
  int dkstream_wb_word (dk_stream_t *st, dk_word w);
  
  int dkstream_wb_uword (dk_stream_t *st, dk_uword w);
  
  int dkstream_wb_dword (dk_stream_t *st, dk_dword w);
  
  int dkstream_wb_udword (dk_stream_t *st, dk_udword w);
  
  int dkstream_wb_string (dk_stream_t *st, char *str);
  
  int dkstream_rb_word (dk_stream_t *st, dk_word *w);
  
  int dkstream_rb_uword (dk_stream_t *st, dk_uword *w);
  
  int dkstream_rb_dword (dk_stream_t *st, dk_dword *w);
  
  int dkstream_rb_udword (dk_stream_t *st, dk_udword *w);
  
  char *dkstream_rb_string (dk_stream_t *st);
  
  dk_stream_suffix_t *dkstream_get_read_suffixes (void);
  
  dk_stream_suffix_t *dkstream_get_write_suffixes (void);
  
  unsigned long dkstream_get_bytes_written (dk_stream_t *st);
  
  dk_stream_t *dkstream_for_file (FILE *f);
  
  dk_stream_t *dkstream_for_gz (gzFile gzf);
  
  dk_stream_t *dkstream_for_bz2 (BZFILE *bzf);
  
=head1	DESCRIPTION

This module provides functions for an abstract I/O layer. 
To do I/O a dk_stream_t structure is created, this structure contains
pointers to additional data and a handler function (callback function)
invoked to deal with the details.

The dkstream_new() function creates a I<dk_stream_t> structure using
the given additional data and handler function. On success it returns
a valid pointer, NULL on error. If the stream was created successfully
it must be destroyed using the dkstream_delete() function after usage.

The dkstream_openfile(), dkstream_opengz() and dkstream_openbz2()
functions create I<dk_stream_t> structures to access files,
gzip-compressed or bzip2-compressed files.
The I<name> parameter specifies the file name, I<mode> specifies
how to use the file (same as the modes in fopen()). The I<ign>
parameter indicates which security checks are to be skipped.
The I<reason> parameter points to a variable which is used to store
a check identifier if a security check denies to open the file.
The following security checks are performed to avoid symlink attacks
when opening files for write access (or combined access including
write operations):

=over 4

=item	* DK_SF_SEC_OWNER

The owner of the link is not the owner of the target file.

=item	* DK_SF_SEC_WO

The symlink is placed in a world writable directory.

=item	* DK_SF_SEC_WG

The symlink is placed in a group writable directory.

=item	* DK_SF_SEC_DIR

The specified file name points to a directory instead of a
regular file.

=back

Note: If the application uses the dkapp module you should use
the dkapp_stream_openfile(), dkapp_stream_opengz() and
dkapp_stream_openbz2() functions.

The functions to open a stream return a valid pointer on success,
NULL on error. If a stream was opened successfully it must be
closed using the dkstream_close() function after usage.

The dkstream_gets() function reads one line into the given buffer
of the specified size.

The dkstream_puts() function writes a string to the stream.

The dkstream_read() and dkstream_write() functions can be used
to read and write buffers of bytes from/to the stream.

The I<dkstream_wb_...()> functions write binary data to the stream.
If a string is written to the stream the length of the string without
trailing Null-byte is written first as 32 bit unsigned long in network
byte order.

The I<dkstream_rb_...()> functions read binary data to the stream.
If a string is read the length is read first, a buffer is allocated
dynamically. This buffer must be released using the dk_delete() function
after usage.

=head1	SEE ALSO

The dklibs.pdf file contains more detailed information on streams,
especially about how to write callback handler functions.

When planning to write a handler function for a new I/O mechanism
you should inspect the dkstream.c source. This module contains
handler functions for dealing with files, gzip-compressed files
and bzip2-compressed files which can serve as an example.

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2001-2008, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
