dklibs(3)

NAME
dkstream - generic interface to I/O operations

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);

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 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 dk_stream_t structures to access files, gzip-compressed or bzip2-compressed files. The name parameter specifies the file name, mode specifies how to use the file (same as the modes in fopen()). The ign parameter indicates which security checks are to be skipped. The 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):

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

* DK_SF_SEC_WO
    The symlink is placed in a world writable directory.

* DK_SF_SEC_WG
    The symlink is placed in a group writable directory.

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

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 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 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.

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.

AUTHOR
Dirk Krause

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.