NAME
    File::fgets - Read either one line or X characters from a file

SYNOPSIS
      use File::fgets;

      open my $fh, $file;

      # Read either one line or the first 10 characters, which ever comes first
      my $line = fgets($fh, 10);

DESCRIPTION
    An implementation of the C fgets() function.

    fgets
        my $string = fgets($fh, $limit);

    Reads either one line or at most $limit bytes from the $fh.

    Returns undef at end of file.

    NOTE: unlike C's fgets, this will read $limit characters not $limit - 1.
    Perl doesn't have to leave room for a null byte.

EXAMPLE
    The following example demonstrates using fgets() to read in at most 5
    characters at a time.

      use File::fgets;

      open my $write_fh, ">", $file;
      print $write_fh <<END;
      this is
      an example
      of use
      END
      close $write_fh;

      open my $fh, "<", $file;
      while( my $string = fgets($fh, 5) ) {
          $string =~ s{\n}{\\n};  # make newlines show up
          print "--$string--\n";
      }

    The result will be:

      --this --
      --is\n--
      --an ex--
      --ample--
      --\n--
      --of us--
      --e\n--

NOTES
    This is implemented as a wrapper around the C fgets() function and is
    extremely efficient UNLESS the filehandle does not have an underlying
    fileno. For example, if its given a tied filehandle. Then it falls back
    to a Perl implementation.

LICENSE
    Copyright 2010 by Michael G Schwern <schwern@pobox.com>.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    See http://www.perl.com/perl/misc/Artistic.html

    Send bugs, feedback, ideas and suggestions via
    https://rt.cpan.org/Public/Dist/Display.html?Name=File-fgets or
    <bugs-File-fgets@rt.cpan.org>

    The latest version of this software can be found at
    http://github.com/schwern/File-fgets

SEE ALSO
    File::GetLineMaxLength