GNU Info

(libc.info)Hook Functions

---

Prev: Streams and Cookies Up: Custom Streams

---

Enter node , (file) or (file)node

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 Note: 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 Note: 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 Note: 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.

 - Data Type: cookie_read_function
     This is the data type that the read function for a custom stream
     should have.  If you declare the function as shown above, this is
     the type it will have.

 - Data Type: cookie_write_function
     The data type of the write function for a custom stream.

 - Data Type: cookie_seek_function
     The data type of the seek function for a custom stream.

 - Data Type: cookie_close_function
     The data type of the close function for a custom stream.