.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FFI::C::File 3pm"
.TH FFI::C::File 3pm "2023-02-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
FFI::C::File \- Perl interface to C File pointer
.SH "VERSION"
.IX Header "VERSION"
version 0.15
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use FFI::C::File;
\& 
\& my $file1 = FFI::C::File\->fopen("foo.txt", "w");
\& my $content1 = "hello world!\en";
\& $file1\->fwrite(\e$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 = "\e0" x length $content;
\& $file3\->fread(\e$content3, length $content);
\& print $content3;  # "hello world!\en";
.Ve
.SH "DESCRIPTION"
.IX Header "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 \f(CW\*(C`FILE*\*(C'\fR type this is the case),
and having C native interface can be useful.
.PP
For example, if you have a C function that takes a file pointer:
.PP
.Vb 1
\& void foo(FILE *fp);
.Ve
.PP
You can use it from your Perl code like so:
.PP
.Vb 2
\& use FFI::Platypus 1.00;
\& use FFI::C::File;
\& 
\& my $ffi = FFI::Platypus\->new( api => 1 );
\& $ffi\->attach( foo => [\*(Aqobject(FFI::C::File)\*(Aq] );
\& 
\& my $file = FFI::C::File\->fopen("foo.txt", "r");
\& foo($file);
.Ve
.PP
As long as this class \*(L"owns\*(R" the file pointer it will close it automatically when it falls
out of scope.  If the C \s-1API\s0 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 \f(CW\*(C`new\*(C'\fR constructor).
.PP
.Vb 2
\& use FFI::Platypus 1.00;
\& use FFI::C::File;
\& 
\& my $ffi = FFI::Platypus\->new( api => 1 );
\& $ffi\->attach( foo => [\*(Aqopaque\*(Aq] );
\& 
\& my $file = FFI::C::File\->fopen("foo.txt", "r");
\& my $ptr = $file\->ptr;
\& foo($ptr);
.Ve
.PP
Likewise, if a C \s-1API\s0 returns a file pointer that you are expected to close you can create
a new File object from the opaque pointer using the \f(CW\*(C`new\*(C'\fR constructor.  C:
.PP
.Vb 1
\& FILE *bar();
.Ve
.PP
Perl:
.PP
.Vb 2
\& use FFI::Platypus 1.00;
\& use FFI::C::File;
\& 
\& my $ffi = FFI::Platypus\->new( api => 1 );
\& $ffi\->attach( bar => [] => \*(Aqopaque\*(Aq );
\& 
\& my $ptr = bar();
\& my $file = FFI::C::File\->new($ptr);
\& # can now read/write etc to/from $file
.Ve
.PP
Constructors and methods will throw an exception on errors.  End-of-File (\s-1EOF\s0) is not considered
an error.
.PP
The subclass FFI::C::PosixFile extends this class by adding some \s-1POSIX\s0 extensions for
platforms that support them.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "fopen"
.IX Subsection "fopen"
.Vb 1
\& my $file = FFI::C::File\->fopen($filename, $mode);
.Ve
.PP
Opens the file with the given mode.  See your standard library C documentation for the
exact format of \f(CW$mode\fR.
.SS "tmpfile"
.IX Subsection "tmpfile"
.Vb 1
\& my $file = FFI::C::File\->tmpfile;
.Ve
.PP
Creates and opens a temporary file.  The file is opened as binary file for update.  On
Windows this may require administrator privileges.
.SS "new"
.IX Subsection "new"
.Vb 1
\& my $file = FFI::C::File\->new($ptr);
.Ve
.PP
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.
.SH "METHODS"
.IX Header "METHODS"
.SS "freopen"
.IX Subsection "freopen"
.Vb 1
\& $file\->freopen($filename, $mode);
.Ve
.PP
Re-open the file stream.  If \f(CW$filename\fR is \f(CW\*(C`undef\*(C'\fR, 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.
.PP
On some platforms (Linux, macOS and possibly some others) you can pass \f(CW\*(C`undef\*(C'\fR as
the \f(CW$filename\fR.  This is a way to change the \f(CW$mode\fR without changing the file.
.SS "fread"
.IX Subsection "fread"
.Vb 1
\& my $bytes = $file\->fread(\e$buffer, $size);
.Ve
.PP
Read up to \f(CW$size\fR bytes into \f(CW$buffer\fR.  \f(CW$buffer\fR 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.
.SS "fwrite"
.IX Subsection "fwrite"
.Vb 1
\& my $bytes = $file\->fwrite(\e$buffer, $size);
.Ve
.PP
Write up to \f(CW$size\fR bytes from \f(CW$buffer\fR.  Returns the number of bytes actually written.
.SS "fseek"
.IX Subsection "fseek"
.Vb 1
\& $file\->fseek($offset, $whence);
.Ve
.PP
Seek to the specified location in the file.  \f(CW$whence\fR should be one of the following
(either strings, or constants can be used, the constants can be imported from this module):
.ie n .IP "\*(Aqset\*(Aq | \s-1SEEK_SET\s0" 4
.el .IP "\f(CW\*(Aqset\*(Aq\fR | \s-1SEEK_SET\s0" 4
.IX Item "set | SEEK_SET"
Relative to the start of the file
.ie n .IP "\*(Aqcur\*(Aq | \s-1SEEK_CUR\s0" 4
.el .IP "\f(CW\*(Aqcur\*(Aq\fR | \s-1SEEK_CUR\s0" 4
.IX Item "cur | SEEK_CUR"
Relative to the current location of the file pointer.
.ie n .IP "\*(Aqend\*(Aq | \s-1SEEK_END\s0" 4
.el .IP "\f(CW\*(Aqend\*(Aq\fR | \s-1SEEK_END\s0" 4
.IX Item "end | SEEK_END"
Relative to the end of the file.
.SS "ftell"
.IX Subsection "ftell"
.Vb 1
\& my $offset = $file\->ftell;
.Ve
.PP
Returns the file position indicator for the file pointer.
.SS "rewind"
.IX Subsection "rewind"
.Vb 1
\& $file\->rewind;
.Ve
.PP
Moves the file position indicator to the beginning of the file.
.SS "fflush"
.IX Subsection "fflush"
.Vb 1
\& $file\->fflush;
.Ve
.PP
Flush the file stream.
.SS "clearerr"
.IX Subsection "clearerr"
.Vb 1
\& $file\->clearerr;
.Ve
.PP
Clear the error flag for the file stream.
.SS "feof"
.IX Subsection "feof"
.Vb 1
\& my $bool = $file\->feof;
.Ve
.PP
Returns true if the end of file has been reached.  False otherwise.
.SS "ferror"
.IX Subsection "ferror"
.Vb 1
\& my $error = $file\->ferror;
.Ve
.PP
Returns the file error code.
.SS "take"
.IX Subsection "take"
.Vb 1
\& my $ptr = $file\->take;
.Ve
.PP
Takes ownership of the file from the object and returns the opaque file pointer.
.SS "fclose"
.IX Subsection "fclose"
.Vb 1
\& $file\->close;
.Ve
.PP
Close the file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\s-1FFI::C\s0" 4
.IX Item "FFI::C"
.PD 0
.IP "FFI::C::Array" 4
.IX Item "FFI::C::Array"
.IP "FFI::C::ArrayDef" 4
.IX Item "FFI::C::ArrayDef"
.IP "FFI::C::Def" 4
.IX Item "FFI::C::Def"
.IP "FFI::C::File" 4
.IX Item "FFI::C::File"
.IP "FFI::C::PosixFile" 4
.IX Item "FFI::C::PosixFile"
.IP "FFI::C::Struct" 4
.IX Item "FFI::C::Struct"
.IP "FFI::C::StructDef" 4
.IX Item "FFI::C::StructDef"
.IP "FFI::C::Union" 4
.IX Item "FFI::C::Union"
.IP "FFI::C::UnionDef" 4
.IX Item "FFI::C::UnionDef"
.IP "FFI::C::Util" 4
.IX Item "FFI::C::Util"
.IP "FFI::Platypus::Record" 4
.IX Item "FFI::Platypus::Record"
.PD
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Ollis <plicease@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2020\-2022 by Graham Ollis.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.