iolayer.c - encapsulates different source of data into a single framework.
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
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)
Some of these functions are internal.
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().
io_new_bufchain()
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.
io_new_buffer(data, length
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).
io_new_fd(file)
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.
read_cb
length
buffer
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.
write_cb
seekcb(p, offset, whence) should seek and return the new offset.
seekcb
close_cb(p) should return 0 on success, -1 on failure.
close_cb
destroy_cb(p) should release any memory specific to your callback handlers.
destroy_cb
Also callable as io_new_cb(p, readcb, writecb, seekcb, closecb, destroycb).
io_new_cb(p, readcb, writecb, seekcb, closecb, destroycb)
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().
Destroy an io_glue objects. Should clean up all related buffers.
ig - io_glue object to destroy.
A macro to read a single byte from a buffered I/O glue object.
Returns EOF on failure, or a byte.
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.
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.
size
ig->buf_size
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.
type
i_io_peekn()
Returns -1 on error, 0 if there is no data before EOF, or the number of bytes read into buffer.
Write a single character to the stream.
On success return c, on error returns EOF
Read up to size bytes from the stream io into buffer.
io
Returns the number of bytes read. Returns 0 on end of file. Returns -1 on error.
Write to the given I/O stream.
Returns the number of bytes written.
Seek within the stream.
Acts like perl's seek.
Flush any buffered output.
Returns true on success,
Flush any pending output and perform the close action for the stream.
Returns 0 on success.
Read up to size-1 bytes from the stream ig into buffer.
ig
If the byte end_of_line is seen then no further bytes will be read.
end_of_line
Returns the number of bytes read.
Always NUL terminates the buffer.
NUL
Do common initialization for io_glue objects.
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.
Dump the base fields of an io_glue object to stdout.
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.
Hex dump the data between start and end.
start
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.
bias == 0
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
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
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
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
Does the reading from a buffer source
Does nothing, returns -1
Implements seeking for a buffer source.
Advances the buffer chain to the next link - extending if necessary. Also adjusts the cpos and tfill counters as needed.
ieb - buffer chain object
frees all resources used by a buffer chain.
Read callback for file descriptor IO objects.
Arnar M. Hrafnkelsson <addi@umich.edu>
Imager(3)
To install Imager, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Imager
CPAN shell
perl -MCPAN -e shell install Imager
For more information on module installation, please visit the detailed CPAN module installation guide.