lib/Imager/IO.pod

   1 =head1 NAME
   2
   3 Imager::IO - Imager's io_layer object.
   4
   5 =head1 SYNOPSIS
   6
   7   # Imager supplies Imager::IO objects to various callbacks
   8   my $IO = ...;
   9
  10   my $count = $IO->write($data);
  11   my $count = $IO->read($buffer, $max_count);
  12   my $position = $IO->seek($offset, $whence);
  13   my $status = $IO->close;
  14
  15 =head1 DESCRIPTION
  16
  17 Imager uses an abstraction when dealing with image files to allow the
  18 same code to work with disk files, in memory data and callbacks.
  19
  20 If you're writing an Imager file handler your code will be passed an
  21 Imager::IO object to write to or read from.
  22
  23 =head1 METHODS
  24
  25 =over
  26
  27 =item write
  28
  29 Call to write to the file.  Returns the number of bytes written.  The
  30 data provided may contain only characters \x00 to \xFF - characters
  31 outside this range will cause this method to croak().
  32
  33 If you supply a UTF-8 flagged string it will be converted to a byte
  34 string, which may have a performance impact.
  35
  36 Returns -1 on error, though in most cases if the result of the write
  37 isn't the number of bytes supplied you'll want to treat it as an error
  38 anyway.
  39
  40 =item read
  41
  42   my $buffer;
  43   my $count = $io->read($buffer, $max_bytes);
  44
  45 Reads up to I<$max_bytes> bytes from the current position in the file
  46 and stores them in I<$buffer>.  Returns the number of bytes read on
  47 success or an empty list on failure.  Note that a read of zero bytes
  48 is B<not> a failure, this indicates end of file.
  49
  50 =item read2
  51
  52   my $buffer = $io->read2($max_bytes);
  53
  54 An alternative interface to read, that might be simpler to use in some
  55 cases.
  56
  57 Returns the data read or an empty list.
  58
  59 =item seek
  60
  61   my $new_position = $io->seek($offset, $whence);
  62
  63 Seek to a new position in the file.  Possible values for I<$whence> are:
  64
  65 =over
  66
  67 =item *
  68
  69 C<SEEK_SET> - I<$offset> is the new position in the file.
  70
  71 =item *
  72
  73 C<SEEK_CUR> - I<$offset> is the offset from the current position in
  74 the file.
  75
  76 =item *
  77
  78 C<SEEK_END> - I<$offset> is the offset relative to the end of the
  79 file.
  80
  81 =back
  82
  83 Note that seeking past the end of the file may or may not result in an
  84 error.
  85
  86 Returns the new position in the file, or -1 on error.
  87
  88 =item close
  89
  90   my $result = $io->close;
  91
  92 Call when you're with the file.  If the IO object is connected to a
  93 file this won't close the file handle, but buffers may be flushed (if
  94 any).
  95
  96 Returns 0 on success, -1 on failure.
  97
  98 =back
  99
 100 =head1 AUTHOR
 101
 102 Tony Cook <tony@imager.perl.org>
 103
 104 =head1 SEE ALSO
 105
 106 Imager, Imager::Files
 107
 108 =cut
 109