NAME

src/pmc/filehandle.pmc - FileHandle PMC

DESCRIPTION

The FileHandle PMC performs I/O operations on a source or destination file.

Vtable Functions

void init()

Initializes a newly created FileHandle object.

PMC *clone()

Create a copy of the filehandle.

void mark()

Mark active filehandle data as live.

void destroy()

Flushes the buffer and handle and closes the handle.

INTVAL get_integer_keyed_int(INTVAL key)

Shortcut to get the value of some attributes. For internal usage only, subject to change without notice.

void set_integer_keyed_int(INTVAL key, INTVAL value)

Shortcut to set the value of some attributes For internal usage only, subject to change without notice.

INTVAL get_bool()

Return false if a previous read attempted to read past the end of the underlying filehandle. Note that this method may return true even if there are no bytes remaining if the most recent read requested the exact number of bytes remaining in the file.

Methods

METHOD open(STRING *filename :optional, STRING *mode :optional)

Opens the file at the given filename (including path) with the given mode. The invocant is modified and becomes an open filehandle. A copy of the invocant is also returned by the method (some subclasses may create this as the primary filehandle, rather than modifying the invocant).Exceptions:EXCEPTION_PIO_ERROR with the following messages:Empty filename

    "Cannot open FileHandle, no path"

Already open filehandle

    "Cannot reopen already open FileHandle"

Invalid handle, no errno as with ISDIR:

    "Unable to open filehandle from path '$path'"

Invalid handle (fd < 0), or other error:

    "Unable to open filehandle from path '$path': $strerror($errno)"

EXCEPTION_INVALID_OPERATION with:

    "Invalid mode for file open"

METHOD isatty()

Returns a boolean value indicating whether SELF is a console/tty.

METHOD is_closed()

Test if the filehandle is closed.

METHOD readline_interactive(STRING *prompt)

Read a line from the filehandle and return it in a string.

METHOD readall(STRING *name);

Read the contents of a file named name into a Parrot string. On a filehandle object that isn't opened yet, the path to a file can be passed to readall and it will open a filehandle on that file, read in the contents, and close the filehandle.

  .local pmc pio
  pio = new 'FileHandle'
  $S0 = pio.'readall'('the_file')

If the filehandle is already open, then no file path should be passed. The readall method will read the rest of the contents of the file, and will not close the filehandle when finished.

  pio = open 'the_file', 'r'
  $S0 = pio.'readall'()

To ensure readall semantics seek to position 0 first.

METHOD flush()

Flushes the filehandle.

METHOD print([INTVAL|FLOATVAL|STRING *|PMC*] value)

Print the passed in integer, number, string, or PMC to the filehandle. (Integers, numbers, and strings are auto-boxed as PMCs.)

METHOD buffer_type(STRING *new_type :optional)

Set or retrieve the buffering behavior for the filehandle. The argument and return value are one of the following:

unbuffered

Buffering disabled, bytes are sent as soon as possible.

line-buffered

Line buffering, bytes are sent when a record separator is encountered.

full-buffered

Full buffering, bytes are sent when the buffer is full.

METHOD buffer_size(INTVAL new_size :optional)

Set or retrieve the buffer size for the filehandle.

METHOD mode()

Retrieve the read mode string for the filehandle.

METHOD eof()

Return true if a previous read attempted to read past the end of the underlying filehandle. Note that this method may return false even if there are no bytes remaining if the most recent read requested the exact number of bytes remaining in the file.

METHOD handle()

Returns the INTVAL used by the OS to identify this filehandle.

METHOD exit_status()

If this is a pipe, return the exit status of the child process.

METHOD tell()

Get the file position of the stream. 2 INTVALs are returned. The first is the position. The second is the position shifted down by 32 bits to handle overflows on 32-bit systems.

METHOD seek(INTVAL whence, INTVAL offs, INTVAL offs_overflow)

Set the file position to an offset specified by offs (and optionally offs_overflow). whence determines from where in the file the offset is taken.

 Whence Value      Meaning
 0                 Seek from the beginning of the file
 1                 Seek from the current position
 2                 Seek from the end of the file

offs_overflow is optional and is used to handle offsets higher than 2Gb on 32bit systems.

METHOD peek()

Returns the next byte from the stream, but does not remove it.

METHOD setasync()

METHOD setblocking()

*/

} /* end pmclass */

/* * Local variables: * c-file-style: "parrot" * End: * vim: expandtab shiftwidth=4 cinoptions='\:2=2' : */