Ubuntu Manpage: FFI::C::File - Perl interface to C File pointer

NAME

       FFI::C::File - Perl interface to C File pointer

VERSION

       version 0.15

SYNOPSIS

        use FFI::C::File;

        my $file1 = FFI::C::File->fopen("foo.txt", "w");
        my $content1 = "hello world!\n";
        $file1->fwrite(\$content1, length $content);
        $file1->fclose;

        my $file2 = FFI::C::File->fopen("foo.txt", "r");
        # take gets the file pointer, $file2 is no longer
        # usable.
        my $ptr = $file2->take;

        # reconstitute the File object using the same file
        # pointer
        my $file3 = FFI::C::File->new($ptr);
        my $content3 = "\0" x length $content;
        $file3->fread(\$content3, length $content);
        print $content3;  # "hello world!\n";

DESCRIPTION

       This class provides an interface to the standard C library file pointers.  Normally from
       Perl you want to use the native Perl file interfaces, but sometimes you might be working
       with a C library that uses C library file pointers (anytime you see the "FILE*" type this
       is the case), and having C native interface can be useful.

       For example, if you have a C function that takes a file pointer:

        void foo(FILE *fp);

       You can use it from your Perl code like so:

        use FFI::Platypus 1.00;
        use FFI::C::File;

        my $ffi = FFI::Platypus->new( api => 1 );
        $ffi->attach( foo => ['object(FFI::C::File)'] );

        my $file = FFI::C::File->fopen("foo.txt", "r");
        foo($file);

       As long as this class "owns" the file pointer it will close it automatically when it falls
       out of scope.  If the C API you are calling is taking ownership of the file pointer and is
       expected to close the file itself, then you can use the take method to take the file
       pointer.  Once this method is called, the file object is no longer usable (though it can
       be later reconstituted using the "new" constructor).

        use FFI::Platypus 1.00;
        use FFI::C::File;

        my $ffi = FFI::Platypus->new( api => 1 );
        $ffi->attach( foo => ['opaque'] );

        my $file = FFI::C::File->fopen("foo.txt", "r");
        my $ptr = $file->ptr;
        foo($ptr);

       Likewise, if a C API returns a file pointer that you are expected to close you can create
       a new File object from the opaque pointer using the "new" constructor.  C:

        FILE *bar();

       Perl:

        use FFI::Platypus 1.00;
        use FFI::C::File;

        my $ffi = FFI::Platypus->new( api => 1 );
        $ffi->attach( bar => [] => 'opaque' );

        my $ptr = bar();
        my $file = FFI::C::File->new($ptr);
        # can now read/write etc to/from $file

       Constructors and methods will throw an exception on errors.  End-of-File (EOF) is not
       considered an error.

       The subclass FFI::C::PosixFile extends this class by adding some POSIX extensions for
       platforms that support them.

CONSTRUCTOR

   fopen
        my $file = FFI::C::File->fopen($filename, $mode);

       Opens the file with the given mode.  See your standard library C documentation for the
       exact format of $mode.

   tmpfile
        my $file = FFI::C::File->tmpfile;

       Creates and opens a temporary file.  The file is opened as binary file for update.  On
       Windows this may require administrator privileges.

   new
        my $file = FFI::C::File->new($ptr);

       Create a new File instance object from the opaque pointer.  Note that it isn't possible to
       do any error checking on the type, so make sure that the pointer you are providing really
       is a C file pointer.

METHODS

   freopen
        $file->freopen($filename, $mode);

       Re-open the file stream.  If $filename is "undef", then the same file is reopened.  This
       can be useful for reopening a file in a different mode.  Note that the mode changes that
       are allowed are platform dependent.

       On some platforms (Linux, macOS and possibly some others) you can pass "undef" as the
       $filename.  This is a way to change the $mode without changing the file.

   fread
        my $bytes = $file->fread(\$buffer, $size);

       Read up to $size bytes into $buffer.  $buffer must be preallocated, otherwise memory
       corruption will happen.  Returns the number of bytes actually read, which may be fewer
       than the number of bytes requested if the end of file is reached.

   fwrite
        my $bytes = $file->fwrite(\$buffer, $size);

       Write up to $size bytes from $buffer.  Returns the number of bytes actually written.

   fseek
        $file->fseek($offset, $whence);

       Seek to the specified location in the file.  $whence should be one of the following
       (either strings, or constants can be used, the constants can be imported from this
       module):

       'set' | SEEK_SET
           Relative to the start of the file

       'cur' | SEEK_CUR
           Relative to the current location of the file pointer.

       'end' | SEEK_END
           Relative to the end of the file.

   ftell
        my $offset = $file->ftell;

       Returns the file position indicator for the file pointer.

   rewind
        $file->rewind;

       Moves the file position indicator to the beginning of the file.

   fflush
        $file->fflush;

       Flush the file stream.

   clearerr
        $file->clearerr;

       Clear the error flag for the file stream.

   feof
        my $bool = $file->feof;

       Returns true if the end of file has been reached.  False otherwise.

   ferror
        my $error = $file->ferror;

       Returns the file error code.

   take
        my $ptr = $file->take;

       Takes ownership of the file from the object and returns the opaque file pointer.

   fclose
        $file->close;

       Close the file.

AUTHOR

       Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2020-2022 by Graham Ollis.

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

NAME

VERSION

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

METHODS

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE