NAME

src/io/api.c - Parrot I/O API

DESCRIPTION

The Parrot I/O subsystem provides the core I/O functionality for all parts of Parrot. This file implements the public interface to the I/O subsystem. Common utility functions that aren't part of the public interface are defined in src/io/common.c and utility functions for a specific platform are in src/io/unix.c, src/io/win32.c, or src/io/portable.c. The platform is selected in include/parrot/io.h, based on #defines from the configuration process.

The FileHandle PMC provides the class-based interface for filehandles that is used in Parrot ops.

Generic I/O interface

PMC *Parrot_io_new_pmc: Creates a new I/O filehandle object. The value of flags is set in the returned PMC.
PMC *Parrot_io_open: Creates and returns a FileHandle PMC for a given string path and flags.
PMC *Parrot_io_fdopen: Creates and returns a FileHandle PMC for a given set of flags on an existing, open file descriptor.; This is used particularly to initialize the STD* IO handles onto the OS IO handles (0, 1, 2).
INTVAL Parrot_io_close: Flushes, closes, and destroys the ParrotIO PMC *pmc.
INTVAL Parrot_io_is_closed: Test whether a filehandle is closed.
void Parrot_io_flush: Flushes the ParrotIO PMC *pmc.
STRING *Parrot_io_reads: Return a new STRING* holding up to len bytes.
INTVAL Parrot_io_read: Reads up to len bytes from *pmc and copies them into *buffer.
INTVAL Parrot_io_write: Writes len bytes from *buffer to *pmc.
PIOOFF_T Parrot_io_seek: Moves the read/write position of *pmc to offset bytes from the position indicated by w. Typically w will be 0 for the start of the file, 1 for the current position, and 2 for the end.
PIOOFF_T Parrot_io_tell: Returns the current read/write position of *pmc.
INTVAL Parrot_io_peek: Retrieve the next character in the stream without modifying the stream. Calls the platform-specific implementation of 'peek'.
INTVAL Parrot_io_eof: Returns a boolean value indication whether *pmc's current read/write position is EOF.
INTVAL Parrot_io_puts: Writes *s tp *pmc. C string version.
INTVAL Parrot_io_putps: Writes *s to *pmc. Parrot string version.
INTVAL Parrot_io_fprintf: Writes a C string format with varargs to *pmc.
INTVAL Parrot_io_printf: Writes a C string format with varargs to stdout.
INTVAL Parrot_io_eprintf: Writes a C string format with varargs to stderr.
PIOHANDLE Parrot_io_getfd: Returns *pmc's file descriptor, or 0 if it is not defined.
INTVAL Parrot_io_is_tty: Returns a boolean value indicating whether *pmc is a console/tty.

`Parrot_io_STD*` Functions

PMC *Parrot_io_STDIN: Returns the FileHandle PMC for stdin.
PMC *Parrot_io_STDOUT: Returns the FileHandle PMC for stdout.
PMC *Parrot_io_STDERR: Returns the FileHandle PMC for stderr.

Offset Functions

These are used to create offsets for the seek op.

PIOOFF_T Parrot_io_make_offset: Returns offset.
PIOOFF_T Parrot_io_make_offset32: hi is shifted 32 bytes to the left and ored together with lo. This allows 64-bit seeks with only 32-bit INTVALS.
PIOOFF_T Parrot_io_make_offset_pmc: Returns the return value of the get_integer vtable method on *pmc.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 36:: =back without =over