=over

=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
X<read> X<file, read>

=item read FILEHANDLE,SCALAR,LENGTH

Attempts to read LENGTH I<characters> of data into variable SCALAR
from the specified FILEHANDLE.  Returns the number of characters
actually read, C<0> at end of file, or undef if there was an error (in
the latter case L<C<$!>|perlvar/$!> is also set).  SCALAR will be grown
or shrunk
so that the last character actually read is the last character of the
scalar after the read.

An OFFSET may be specified to place the read data at some place in the
string other than the beginning.  A negative OFFSET specifies
placement at that many characters counting backwards from the end of
the string.  A positive OFFSET greater than the length of SCALAR
results in the string being padded to the required size with C<"\0">
bytes before the result of the read is appended.

The call is implemented in terms of either Perl's or your system's native
L<fread(3)> library function, via the L<PerlIO> layers applied to the
handle.  To get a true L<read(2)> system call, see
L<sysread|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>.

Note the I<characters>: depending on the status of the filehandle,
either (8-bit) bytes or characters are read.  By default, all
filehandles operate on bytes, but for example if the filehandle has
been opened with the C<:utf8> I/O layer (see
L<C<open>|/open FILEHANDLE,MODE,EXPR>, and the L<open>
pragma), the I/O will operate on UTF8-encoded Unicode
characters, not bytes.  Similarly for the C<:encoding> layer:
in that case pretty much any characters can be read.

=back