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