NAME

iolayer.c - encapsulates different source of data into a single framework.

SYNOPSIS

io_glue *ig = io_new_fd( fileno(stdin) );
method = io_reqmeth( IOL_NOSEEK | IOL_MMAP ); // not implemented yet

switch (method) {
case IOL_NOSEEK:
  code that uses ig->readcb()
  to read data goes here.
  break;
case IOL_MMAP:
  code that uses ig->readcb()
  to read data goes here.
  break;
}  

io_glue_destroy(ig);
// and much more

DESCRIPTION

iolayer.c implements the basic functions to create and destroy io_glue objects for Imager. The typical usage pattern for data sources is:

1. Create the source (io_new_fd)
2. Define how you want to get data from it (io_reqmeth)
3. read from it using the interface requested (ig->readdb, ig->mmapcb)
4. Close the source, which 
   shouldn't really close the underlying source. (io_glue DESTROY)

FUNCTION REFERENCE

Some of these functions are internal.

im_io_new_bufchain(ctx) =order 10 =category I/O Layers

Returns a new io_glue object that has the 'empty' source and but can be written to and read from later (like a pseudo file).

Also callable as io_new_bufchain().

im_io_new_buffer(ctx, data, length) =order 10 =category I/O Layers

Returns a new io_glue object that has the source defined as reading from specified buffer. Note that the buffer is not copied.

ctx - an Imager context object
data - buffer to read from
length - length of buffer

Also callable as io_new_buffer(data, length.

im_io_new_fd(ctx, file) =order 10 =category I/O Layers

Returns a new io_glue object that has the source defined as reading from specified file descriptor. Note that the interface to receiving data from the io_glue callbacks hasn't been done yet.

ctx - and Imager context object
file - file descriptor to read/write from

Also callable as io_new_fd(file).

im_io_new_cb(ctx, p, read_cb, write_cb, seek_cb, close_cb, destroy_cb) =category I/O Layers =order 10

Create a new I/O layer object that calls your supplied callbacks.

In general the callbacks should behave like the corresponding POSIX primitives.

• read_cb(p, buffer, length) should read up to length bytes into buffer and return the number of bytes read. At end of file, return 0. On error, return -1.

• write_cb(p, buffer, length) should write up to length bytes from buffer and return the number of bytes written. A return value <= 0 will be treated as an error.

• seekcb(p, offset, whence) should seek and return the new offset.

• close_cb(p) should return 0 on success, -1 on failure.

• destroy_cb(p) should release any memory specific to your callback handlers.

Also callable as io_new_cb(p, readcb, writecb, seekcb, closecb, destroycb).

io_slurp(ig, c) =category I/O Layers

Takes the source that the io_glue is bound to and allocates space for a return buffer and returns the entire content in a single buffer. Note: This only works for io_glue objects created by io_new_bufchain(). It is useful for saving to scalars and such.

 ig - io_glue object
 c  - pointer to a pointer to where data should be copied to

char *data;
size_t size = io_slurp(ig, &data);
... do something with the data ...
myfree(data);

io_slurp() will abort the program if the supplied I/O layer is not from io_new_bufchain().

io_glue_destroy(ig) =category I/O Layers =order 90 =synopsis io_glue_destroy(ig);

Destroy an io_glue objects. Should clean up all related buffers.

ig - io_glue object to destroy.

i_io_getc(ig) =category I/O Layers

A macro to read a single byte from a buffered I/O glue object.

Returns EOF on failure, or a byte.

i_io_peekc(ig) =category I/O Layers

Read the next character from the stream without advancing the stream.

On error or end of file, return EOF.

For unbuffered streams a single character buffer will be setup.

i_io_peekn(ig, buffer, size) =category I/O Layers =synopsis ssize_t count = i_io_peekn(ig, buffer, sizeof(buffer));

Buffer at least size (at most ig->buf_size bytes of data from the stream and return size bytes of it to the caller in buffer.

This ignores the buffered state of the stream, and will always setup buffering if needed.

If no type parameter is provided to Imager::read() or Imager::read_multi(), Imager will call i_io_peekn() when probing for the file format.

Returns -1 on error, 0 if there is no data before EOF, or the number of bytes read into buffer.

i_io_putc(ig, c) =category I/O Layers

Write a single character to the stream.

On success return c, on error returns EOF

i_io_read(io, buffer, size) =category I/O Layers

Read up to size bytes from the stream io into buffer.

Returns the number of bytes read. Returns 0 on end of file. Returns -1 on error.

i_io_write(io, buffer, size) =category I/O Layers =synopsis ssize_t result = i_io_write(io, buffer, size)

Write to the given I/O stream.

Returns the number of bytes written.

i_io_seek(io, offset, whence) =category I/O Layers

Seek within the stream.

Acts like perl's seek.

i_io_flush(io) =category I/O Layers

Flush any buffered output.

Returns true on success,

i_io_close(io) =category I/O Layers

Flush any pending output and perform the close action for the stream.

Returns 0 on success.

i_io_gets(ig, buffer, size, end_of_line) =category I/O Layers =synopsis char buffer[BUFSIZ] =synopsis ssize_t len = i_io_gets(buffer, sizeof(buffer), '\n');

Read up to size-1 bytes from the stream ig into buffer.

If the byte end_of_line is seen then no further bytes will be read.

Returns the number of bytes read.

Always NUL terminates the buffer.

i_io_init(ig, readcb, writecb, seekcb)

Do common initialization for io_glue objects.

i_io_set_buffered(io, buffered) =category I/O Layers

Set the buffering mode of the stream.

If you switch buffering off on a stream with buffering on:

• any buffered output will be flushed.

• any existing buffered input will be consumed before reads become unbuffered.

Returns true on success. This may fail if any buffered output cannot be flushed.

i_io_dump(ig)

Dump the base fields of an io_glue object to stdout.

INTERNAL FUNCTIONS

my_strerror

Calls strerror() and ensures we don't return NULL.

On some platforms it's possible for strerror() to return NULL, this wrapper ensures we only get non-NULL values.

dump_data(start, end, bias)

Hex dump the data between start and end.

If there is more than a pleasing amount of data, either dump the beginning (bias == 0) or dump the end C(<bias != 0>) of the range.

realseek_read(ig, buf, count)

Does the reading from a source that can be seeked on

ig    - io_glue object
buf   - buffer to return data in
count - number of bytes to read into buffer max

realseek_write(ig, buf, count)

Does the writing to a 'source' that can be seeked on

ig    - io_glue object
buf   - buffer that contains data
count - number of bytes to write

realseek_close(ig)

Closes a source that can be seeked on. Not sure if this should be an actual close or not. Does nothing for now. Should be fixed.

ig - data source

realseek_seek(ig, offset, whence)

Implements seeking for a source that is seekable, the purpose of having this is to be able to have an offset into a file that is different from what the underlying library thinks.

ig     - data source
offset - offset into stream
whence - whence argument a la lseek

buffer_read(ig, buf, count)

Does the reading from a buffer source

ig    - io_glue object
buf   - buffer to return data in
count - number of bytes to read into buffer max

buffer_write(ig, buf, count)

Does nothing, returns -1

ig    - io_glue object
buf   - buffer that contains data
count - number of bytes to write

buffer_close(ig)

Closes a source that can be seeked on. Not sure if this should be an actual close or not. Does nothing for now. Should be fixed.

ig - data source

buffer_seek(ig, offset, whence)

Implements seeking for a buffer source.

ig     - data source
offset - offset into stream
whence - whence argument a la lseek

io_bchain_advance(ieb)

Advances the buffer chain to the next link - extending if necessary. Also adjusts the cpos and tfill counters as needed.

ieb   - buffer chain object

io_bchain_destroy()

frees all resources used by a buffer chain.

bufchain_read(ig, buf, count)

Does the reading from a source that can be seeked on

ig    - io_glue object
buf   - buffer to return data in
count - number of bytes to read into buffer max

bufchain_write(ig, buf, count)

Does the writing to a 'source' that can be seeked on

ig    - io_glue object
buf   - buffer that contains data
count - number of bytes to write

bufchain_close(ig)

Closes a source that can be seeked on. Not sure if this should be an actual close or not. Does nothing for now. Should be fixed.

ig - data source

bufchain_seek(ig, offset, whence)

Implements seeking for a source that is seekable, the purpose of having this is to be able to have an offset into a file that is different from what the underlying library thinks.

ig     - data source
offset - offset into stream
whence - whence argument a la lseek

fd_read(ig, buf, count)

Read callback for file descriptor IO objects.

AUTHOR

Arnar M. Hrafnkelsson <addi@umich.edu>

SEE ALSO

Imager(3)