NAME

volstream_open – create a FILE* stream as a volatile stream buffer

SYNOPSIS

#include <volatilestream.h>

FILE *volstream_open(void);

int volstream_trunc(FILE *f, size_t length);

int volstream_getbuf(FILE *f, void **buf, size_t *buflen);

DESCRIPTION

A volatile stream is a stdio FILE* stream as a temporary dynamically allocated (and deallocated) memory buffer.

The volstream_open function opens a stdio stream as a temporary memory buffer. The buffer is dynamically allocated, grows as needed and it is automatically deallocated when the stream is closed.

volstream_trunc truncates the buffer to the requested length. If the current size of the buffer is larger than length the extra data is lost. If the buffer is shorter it is extended and the extended part is filled with null bytes.

volstream_getbuf writes the current address and size of the buffer in *buf and *buflen respectively. These values remain valid only as long as the caller performs no further output on the stream or the stream is closed.

RETURN VALUE

Upon successful completion volstream_open returns a FILE pointer. Otherwise, NULL is returned and errno is set to indicate the error.

volstream_trunc and volstream_getbuf return 0 or -1 if an error occurred. In the event of an error, errno is set to indicate the error.

EXAMPLES

The following example writes all the command arguments in a volatile stream, then it rereads the volatile stream one byte at a time:

#include *stdio.h*
#include *volatilestream.h*
int main(int argc, char *argv[]) {
  FILE *f = volstream_open();
  int c;
  for (argv++; *argv; argv++)
    fprintf(f, "%s\n", *argv);
  fseek(f, 0, SEEK_SET);
  while ((c = getc(f)) != EOF)
    putchar(c);
  fclose(f);
}
    

The following example has the same effect but it rereads the arguments as a memory buffer.

#include *stdio.h*
#include *unistd.h*
#include *volatilestream.h*
int main(int argc, char *argv[]) {
  FILE *f = volstream_open();
  int c;
  for (argv++; *argv; argv++) {
    fprintf(f, "%s\n", *argv);
  }
  fflush(f);
  ssize_t s;
  void *buf;
  volstream_getbuf(f, &buf, &s);
  write(STDOUT_FILENO, buf, s);
  fclose(f);
}
    

AUTHOR

VirtualSquare. Project leader: Renzo Davoli.