NAME

src/io/io_unix.c - UNIX IO layer

DESCRIPTION

This is the Parrot UNIX IO layer. It implements unbuffered, low-level, UNIX-specific functionality.

As "UNIX" is already a generalization, it may be necessary to create separate OS-specific layers for UNIX flavors, to avoid over-complicating this file.

References:

APitUE - W. Richard Stevens, AT&T SFIO, Perl5 (Nick Ing-Simmons)

Functions

flags_to_unix: Returns a UNIX-specific interpretation of flags suitable for passing to open() and fopen() in PIO_unix_open() and PIO_unix_fdopen() respectively.
PIO_unix_init: Sets up the interpreter's standard std* IO handles. Returns 0 on success and -1 on error.
PIO_unix_open: Opens *spath. flags is a bitwise or combination of PIO_F_* values.
PIO_unix_async: Experimental asynchronous IO.; This is available if PARROT_ASYNC_DEVEL is defined.; Only works on Linux at the moment.; Toggles the O_ASYNC flag on the IO file descriptor.
PIO_unix_fdopen: Returns a new ParrotIO with file descriptor fd.
PIO_unix_close: Closes *io's file descriptor.
PIO_unix_isatty: Returns a boolean value indicating whether fd is a console/tty.
PIO_unix_getblksize: Various ways of determining block size.; If passed a file descriptor then fstat() and the stat buffer are used if available.; If called without an argument then the BLKSIZE constant is returned if it was available at compile time, otherwise PIO_BLKSIZE is returned.
PIO_unix_flush: At lowest layer all we can do for flush is to ask the kernel to sync().; XXX: Is it necessary to sync() here?
PIO_unix_read: Calls read() to return up to len bytes in the memory starting at buffer.
PIO_unix_write: Calls write() to write len bytes from the memory starting at buffer to the file descriptor in *io.
PIO_unix_seek: Hard seek.; Calls lseek() to advance the read/write position on *io's file descriptor to offset bytes from the location indicated by whence.
PIO_unix_tell: Returns the current read/write position on *io's file discriptor.

Networking

Define PARROT_NET_DEVEL to enable networking.

These could be native extensions but they probably should be here if we wish to make them integrated with the async IO system.

Very minimal stubs for now, maybe someone will run with these.

PIO_sockaddr_in: PIO_sockaddr_in() is not part of the layer and so must be extern.; XXX: We can probably just write our own routines (htons(), inet_aton(), etc.) and take this out of platform specific compilation
PIO_unix_socket: Uses socket() to create a socket with the specified address family, socket type and protocol number.
PIO_unix_connect: Connects *io's socket to address *r.
PIO_unix_bind: Binds *io's socket to the local address and port specified by *l.
PIO_unix_listen: Listen for new connections. This is only applicable to STREAM or SEQ sockets.
PIO_unix_accept: Accept a new connection and return a newly created ParrotIO socket.
PIO_unix_send: Send the message *s to *io's connected socket.
PIO_unix_recv: Receives a message in **s from *io's connected socket.
PIO_unix_poll: Utility function for polling a single IO stream with a timeout.; Returns a 1 | 2 | 4 (read, write, error) value.; This is not equivalent to any speficic POSIX or BSD socket call, however it is a useful, common primitive.; Not at all usefule --leo.; Also, a buffering layer above this may choose to reimpliment by checking the read buffer.
PIO_unix_pipe: Very limited exec for now.; XXX: Where does this fit, should it belong in the ParrotIOLayerAPI?

HISTORY

Initially written by Melvin Smith (mrjoltcola@mindspring.com).