GNU Info

(libc.info)String Streams

---

Next: Obstack Streams Up: Other Kinds of Streams

---

Enter node , (file) or (file)node

String Streams
--------------

   The `fmemopen' and `open_memstream' functions allow you to do I/O to
a string or memory buffer.  These facilities are declared in `stdio.h'.

 - Function: FILE * fmemopen (void *BUF, size_t SIZE, const char
          *OPENTYPE)
     This function opens a stream that allows the access specified by
     the OPENTYPE argument, that reads from or writes to the buffer
     specified by the argument BUF.  This array must be at least SIZE
     bytes long.

     If you specify a null pointer as the BUF argument, `fmemopen'
     dynamically allocates an array SIZE bytes long (as with `malloc';
     Note: Unconstrained Allocation).  This is really only useful if
     you are going to write things to the buffer and then read them back
     in again, because you have no way of actually getting a pointer to
     the buffer (for this, try `open_memstream', below).  The buffer is
     freed when the stream is closed.

     The argument OPENTYPE is the same as in `fopen' (Note: Opening
     Streams).  If the OPENTYPE specifies append mode, then the
     initial file position is set to the first null character in the
     buffer.  Otherwise the initial file position is at the beginning
     of the buffer.

     When a stream open for writing is flushed or closed, a null
     character (zero byte) is written at the end of the buffer if it
     fits.  You should add an extra byte to the SIZE argument to
     account for this.  Attempts to write more than SIZE bytes to the
     buffer result in an error.

     For a stream open for reading, null characters (zero bytes) in the
     buffer do not count as "end of file".  Read operations indicate
     end of file only when the file position advances past SIZE bytes.
     So, if you want to read characters from a null-terminated string,
     you should supply the length of the string as the SIZE argument.

   Here is an example of using `fmemopen' to create a stream for
reading from a string:

     #include <stdio.h>
     
     static char buffer[] = "foobar";
     
     int
     main (void)
     {
       int ch;
       FILE *stream;
     
       stream = fmemopen (buffer, strlen (buffer), "r");
       while ((ch = fgetc (stream)) != EOF)
         printf ("Got %c\n", ch);
       fclose (stream);
     
       return 0;
     }

   This program produces the following output:

     Got f
     Got o
     Got o
     Got b
     Got a
     Got r

 - Function: FILE * open_memstream (char **PTR, size_t *SIZELOC)
     This function opens a stream for writing to a buffer.  The buffer
     is allocated dynamically (as with `malloc'; Note: Unconstrained
     Allocation) and grown as necessary.

     When the stream is closed with `fclose' or flushed with `fflush',
     the locations PTR and SIZELOC are updated to contain the pointer
     to the buffer and its size.  The values thus stored remain valid
     only as long as no further output on the stream takes place.  If
     you do more output, you must flush the stream again to store new
     values before you use them again.

     A null character is written at the end of the buffer.  This null
     character is _not_ included in the size value stored at SIZELOC.

     You can move the stream's file position with `fseek' or `fseeko'
     (Note: File Positioning).  Moving the file position past the end
     of the data already written fills the intervening space with
     zeroes.

   Here is an example of using `open_memstream':

     #include <stdio.h>
     
     int
     main (void)
     {
       char *bp;
       size_t size;
       FILE *stream;
     
       stream = open_memstream (&bp, &size);
       fprintf (stream, "hello");
       fflush (stream);
       printf ("buf = `%s', size = %d\n", bp, size);
       fprintf (stream, ", world");
       fclose (stream);
       printf ("buf = `%s', size = %d\n", bp, size);
     
       return 0;
     }

   This program produces the following output:

     buf = `hello', size = 5
     buf = `hello, world', size = 12