NAME

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

SYNOPSIS

       #include <volatilestream.h>

       FILE *volstream_open(void);

       struct volstream;

       FILE *volstream_openv(struct volstream **vols);

       int volstream_trunc(struct volstream *vols, size_tlength);

       void *volstream_getbuf(struct volstream *vols);

       size_t volstream_getsize(struct volstream *vols);

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.

       The  function  volstream_openv has the same effect of volstream_open but it stores in vols a pointer that
       can be later used for volstream_trunc, volstream_getbuf and volstream_getsize.

       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  and  volstream_getsize return the current address and size of the buffer, respectively.
       These values remain valid only as long as the caller performs no further output  on  the  stream  or  the
       stream is closed.

       fflush  is  required  before  volstream_trunc, volstream_getbuf and volstream_getsize to flush the stream
       buffers.

RETURN VALUE

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

       volstream_trunc returns -1 in case of error, 0 otherwise.

       volstream_getbuf and volstream_getsize return the current address and size of the buffer, respectively.

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[]) {
             struct volstream *vols;
             FILE *f = volstream_openv(&vols);
             int c;
             for (argv++; *argv; argv++) {
               fprintf(f, "%s\n", *argv);
             }
             fflush(f);
             ssize_t s = volstream_getsize(vols);
             char *buf = volstream_getbuf(vols);
                write(STDOUT_FILENO, buf, s);
                fclose(f);
           }

AUTHOR

       VirtualSquare. Project leader: Renzo Davoli.

VirtualSquare                                    September 2020                                VOLSTREAM_OPEN(3)