12.21.3.2 Custom Stream Hook Functions

Here are more details on how you should define the four hook functions that a custom stream needs.

You should define the function to read data from the cookie as:

     ssize_t reader (void *cookie, char *buffer, size_t size)

This is very similar to the read function; see I/O Primitives. Your function should transfer up to size bytes into the buffer, and return the number of bytes read, or zero to indicate end-of-file. You can return a value of -1 to indicate an error.

You should define the function to write data to the cookie as:

     ssize_t writer (void *cookie, const char *buffer, size_t size)

This is very similar to the write function; see I/O Primitives. Your function should transfer up to size bytes from the buffer, and return the number of bytes written. You can return a value of -1 to indicate an error.

You should define the function to perform seek operations on the cookie as:

     int seeker (void *cookie, fpos_t *position, int whence)

For this function, the position and whence arguments are interpreted as for fgetpos; see Portable Positioning. In the GNU library, fpos_t is equivalent to off_t or long int, and simply represents the number of bytes from the beginning of the file.

After doing the seek operation, your function should store the resulting file position relative to the beginning of the file in position. Your function should return a value of 0 on success and -1 to indicate an error.

You should define the function to do cleanup operations on the cookie appropriate for closing the stream as:

     int cleaner (void *cookie)

Your function should return -1 to indicate an error, and 0 otherwise.