FFI::C::File(3pm)

💖 FFI::C::File 💖

okay bestie, so this is FFI::C::File, a Perl interface to the C File pointer — and it's giving extremely useful, no cap. It lives in the User Contributed Perl Documentation corner of your 3pm manpages, and I'm gonna walk you through every single bit of it. 🫶

✨ VERSION ✨

version 0.15 — she's serving, she's fresh, she's that girl.

🌸 SYNOPSIS 🌸

okay so here's the vibe, look:

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";

(and yes, if you clocked that $content shows up where you'd maybe expect $content1, that's literally how the original is written, so I'm keeping it exactly as it is, periodt. 💅)

---

💜 DESCRIPTION 💜

So basically this class is a whole interface to the standard C library file pointers. Normally when you're in Perl you'd just use the native Perl file interfaces, right? but sometimes you're out here working with a C library that uses C library file pointers — and anytime you see the FILE* type, that's exactly what's happening — and having a C native interface can be useful. lowkey iconic. 🌈

For example, say you've got 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, she will close it automatically when it falls out of scope — like, she handles her business. 💖 But if the C API you're 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). So like, don't come for her afterwards, she's done. 😭

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're 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

⚠️ Heads up bestie: constructors and methods will throw an exception on errors. End-of-File (EOF) is not considered an error though, so don't stress about that one. 🧚

The subclass FFI::C::PosixFile extends this class by adding some POSIX extensions for platforms that support them. she's the younger sister and she's got range. 👑

---

🎀 CONSTRUCTOR 🎀

✨ fopen

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

Opens the file with the given mode. For the exact format of $mode, go check your standard library C documentation — that's where the tea is. 🍓

✨ 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. (yeah. Windows things. 🙈)

✨ 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. no vibe checks available here, you're on your own, so be careful. 💀

---

🦋 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. cute little trick, iykyk. ✨

💫 fread

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

Read up to $size bytes into $buffer. $buffer must be preallocated, otherwise memory corruption will happen — and that is not the kind of chaos we're manifesting, so preallocate her. 😭 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. like "where are we rn" but for files. 📍

💫 rewind

$file->rewind;

Moves the file position indicator to the beginning of the file. it's giving take me back to the start. 🔥

💫 fflush

$file->fflush;

Flush the file stream.

💫 clearerr

$file->clearerr;

Clear the error flag for the file stream. it's the "forget about it bestie, we move" method. 💅

💫 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. (after this, the object is no longer usable — she gave everything away. 🫶)

💫 fclose

$file->close;

Close the file.

---

⭐ SEE ALSO ⭐

• FFI::C
• FFI::C::Array
• FFI::C::ArrayDef
• FFI::C::Def
• FFI::C::File
• FFI::C::PosixFile
• FFI::C::Struct
• FFI::C::StructDef
• FFI::C::Union
• FFI::C::UnionDef
• FFI::C::Util
• FFI::Platypus::Record

---

👑 AUTHOR 👑

Graham Ollis <plicease@cpan.org> — shoutout to the author, absolutely carrying this whole module. 💜

🌈 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.

---

and that's the whole thing bestie, no notes. this page came out of perl v5.36.0 and is dated 2023-02-06, and it lives at FFI::C::File(3pm) — so go forth and interface with C file pointers, you absolute icon. 💖✨🎀🦋🌸💅🫶