dkstream(3) - Linux man page

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