To contents Next section

9.1 File management - Stdio.File

CLASS
Stdio.File This is the basic I/O object, it provides socket communication as well as file access. It does not buffer reads and writes or provide line-by-line reading, that is done in the FILE object. Stdio.File is completely written in C. What follows is a description of all the functions in Stdio.File.

METHOD
Stdio.File.create - init file struct

SYNTAX
object(Stdio.File) Stdio.File();
object(Stdio.File) Stdio.File(string filename);
object(Stdio.File) Stdio.File(string filename, string mode);
object(Stdio.File) Stdio.File(string filename, string mode, int mask);
object(Stdio.File) Stdio.File(string fd);
object(Stdio.File) Stdio.File(int fd);
object(Stdio.File) Stdio.File(int fd, string mode);

DESCRIPTION
There are four different ways to clone a File. The first is to clone it without any arguments, in which case the you have to call open(), connect() or some other method which connects the File object with a stream.

However, instead of cloning and then calling open(), you can clone the File with a filename and open mode. This is the same thing as cloning and then calling open, except shorter and faster. Default open mode is "r" and default mask is 0666.

Alternatively, you can clone a File with "stdin", "stdout" or "stderr" as argument. This will open the specified standard stream.

For the advanced users, you can use the file descriptors of the systems (note: emulated by pike on some systems - like NT). This is only useful for streaming purposes on unix systems. This is not recommended at all if you don't know what you're into. Default mode for this is "rw".

NOTE
Open mode will be filtered through the system UMASK. You might need to use chmod later.

SEE ALSO
clone and Stdio.File->open

METHOD
Stdio.File.open - open a file

SYNTAX
int open(string filename, string how);
int open(string filename, string how, int mode);

DESCRIPTION
Open a file for read, write or append. The variable how should contain one or more of the following letters:

'r' open file for reading
'w' open file for writing
'a' open file for append (use with 'w')
't' truncate file at open (use with 'w')
'c' create file if it doesn't exist (use with 'w')
'x' fail if file already exist (use with 'c')

How should _always_ contain at least one of 'r' or 'w'.

The third argument is protection bits if the file is created. Default is 0666 (all read+write, in octal notation).

RETURNS
1 on success, 0 otherwise

SEE ALSO
Stdio.File->close

METHOD
Stdio.File.close - close a file

SYNTAX
int close(string how);
int close();

DESCRIPTION
Close the file. Optionally, specify "r", "w" or "rw" to close just the read, just the write or both read and write part of the file respectively. Note that this function will not call the close_callback.

SEE ALSO
Stdio.File->open

METHOD
Stdio.File.read - read data from a file or stream

SYNTAX
string read(int nbytes);
string read(int nbytes, int notall);
string read();

DESCRIPTION
Read tries to read nbytes bytes from the file, and return it as a string. If something goes wrong, zero is returned.

If a one is given as second argument to read(), read will not try its best to read as many bytes as you asked it to read, it will merely try to read as many bytes as the system read function will return. This mainly useful with stream devices which can return exactly one row or packet at a time.

If no arguments are given, read will read to the end of the file/stream.

SEE ALSO
Stdio.File->read_oob and Stdio.File->write

METHOD
Stdio.File.read_oob - read out-of-band data from a stream

SYNTAX
string read_oob(int nbytes);
string read_oob(int nbytes, int notall);
string read_oob();

DESCRIPTION
Tries to read nbytes bytes of out-of-band data from the stream, and returns it as a string. If something goes wrong, zero is returned.

If a one is given as a second argument to read_oob(), only as many bytes of out-of-band data as are currently available will be returned.

If no arguments are given, read_oob will read to the end of the stream.

NOTE
This function is only available if the option '--with-oob' was specified when Pike was compiled.

It is not guaranteed that all out-of-band data sent from the other end will be received. Most streams only allow for a single byte of out-of-band data at a time.

SEE ALSO
Stdio.File->read and Stdio.File->write_oob

METHOD
Stdio.File.write - write data to a file or stream

SYNTAX
int write(string data);

DESCRIPTION
Write data to file or stream and return how many bytes that were actually written. 0 is returned in nonblocking mode if it was not possible to write anything without blocking. -1 is returned if something went wrong and no bytes were written.

SEE ALSO
Stdio.File->read and Stdio.File->write_oob

METHOD
Stdio.File.write_oob - write out-of-band data to a stream

SYNTAX
int write_oob(string data);

DESCRIPTION
Writes out-of-band data to a stream and returns how many bytes that were actually written. -1 is returned if something went wrong and no bytes were written.

NOTE
This function is only available if the option '--with-oob' was specified when Pike was compiled.

It is not guaranteed that all out-of-band data will be received at the other end. Most streams only allow for a single byte of out-of-band data at a time. Some streams will send the rest of the data as ordinary data.

SEE ALSO
Stdio.File->read_oob and Stdio.File->write

METHOD
Stdio.File.seek - seek to a position in a file

SYNTAX
int seek(int pos);

DESCRIPTION
Seek to a position in a file, if pos is less than zero, seek to position pos relative end of file. Returns -1 for failure, or the new position in the file when successful.

SEE ALSO
Stdio.File->tell

METHOD
Stdio.File.tell - tell where we are in a file

SYNTAX
int tell();

DESCRIPTION
Returns the current position in the file.

SEE ALSO
Stdio.File->seek

METHOD
Stdio.File.truncate - truncate a file

SYNTAX
int truncate(int length);

DESCRIPTION
Truncates a file to that length. Returns 1 if ok, 0 if failed.

SEE ALSO
Stdio.File->open

METHOD
Stdio.File.stat - do file_stat on an open file

SYNTAX
array(int) stat();

DESCRIPTION
This function returns the same information as the function file_stat, but for the file it is called in. If file is not an open file, zero will be returned. Zero is also returned if file is a pipe or socket.

SEE ALSO
file_stat

METHOD
Stdio.File.errno - what was last error?

SYNTAX
int errno();

DESCRIPTION
Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.

METHOD
Stdio.File.set_buffer - set internal socket buffer

SYNTAX
void set_buffer(int bufsize, string mode);
void set_buffer(int bufsize);

DESCRIPTION
This function sets the internal buffer size of a socket or stream. The second argument allows you to set the read or write buffer by specifying "r" or "w". It is not guaranteed that this function actually does anything, but it certainly helps to increase data transfer speed when it does.

SEE ALSO
Stdio.File->open_socket and Stdio.Port->accept

METHOD
Stdio.File.set_nonblocking - make stream nonblocking

SYNTAX
void set_nonblocking(function(mixed, string:void) read_callback,
function(mixed:void) write_callback,
function(mixed:void) close_callback);
or
void set_nonblocking(function(mixed, string:void) read_callback,
function(mixed:void) write_callback,
function(mixed:void) close_callback,
function(mixed, string:void) read_oob_callback,
function(mixed:void) write_oob_callback);
or
void set_nonblocking();

DESCRIPTION
This function sets a stream to nonblocking mode. When data arrives on the stream, read_callback will be called with some or all of this data. When the stream has buffer space over for writing, write_callback is called so you can write more data to it. If the stream is closed at the other end, close_callback is called.

When out-of-band data arrives on the stream, read_oob_callback will be called with some or all of this data. When the stream allows out-of-band data to be sent, write_oob_callback is called so that you can write out-of-band data to it.

All callbacks will have the id of file as first argument when called.

If no arguments are given, the callbacks are not changed. The stream is just set to nonblocking mode.

NOTE
Out-of-band data is only supported if Pike was compiled with the option '--with-oob'.

SEE ALSO
Stdio.File->set_blocking and Stdio.File->set_id

METHOD
Stdio.File.set_read_callback - set the read callback

SYNTAX
void set_read_callback(function read_callback)

DESCRIPTION
This function sets the read callback for the file. The read callback is called whenever there is data to read from the file. Note that this function does not set the file nonblocking.

SEE ALSO
Stdio.File->set_nonblocking

METHOD
Stdio.File.set_write_callback - set the write callback

SYNTAX
void set_write_callback(function write_callback)

DESCRIPTION
This function sets the write callback for the file. The write callback is called whenever there is buffer space available to write to for the file. Note that this function does not set the file nonblocking.

SEE ALSO
Stdio.File->set_nonblocking

METHOD
Stdio.File.set_close_callback - set the close callback

SYNTAX
void set_close_callback(function close_callback)

DESCRIPTION
This function sets the close callback for the file. The close callback is called when the remote end of a socket or pipe is closed. Note that this function does not set the file nonblocking.

SEE ALSO
Stdio.File->set_nonblocking

METHOD
Stdio.File.set_blocking - make stream blocking

SYNTAX
void set_blocking();

DESCRIPTION
This function sets a stream to blocking mode. i.e. all reads and writes will wait until data has been written before returning.

SEE ALSO
Stdio.File->set_nonblocking

METHOD
Stdio.File.set_id - set id of this file

SYNTAX
void set_id(mixed id);

DESCRIPTION
This function sets the id of this file. The id is mainly used as an identifier that is sent as the first arguments to all callbacks. The default id is 0. Another possible use of the id is to hold all data related to this file in a mapping or array.

SEE ALSO
Stdio.File->query_id

METHOD
Stdio.File.query_id - get id of this file

SYNTAX
mixed query_id();

DESCRIPTION
This function returns the id of this file.

SEE ALSO
Stdio.File->set_id

METHOD
Stdio.File.query_read_callback - return the read callback function

SYNTAX
function query_read_callback();

DESCRIPTION
This function returns the read_callback, which is set with set_nonblocking or set_read_callback.

SEE ALSO
Stdio.File->set_nonblocking and Stdio.File->set_read_callback

METHOD
Stdio.File.query_write_callback - return the write callback function

SYNTAX
function query_write_callback();

DESCRIPTION
This function returns the write_callback, which is set with set_nonblocking or set_write_callback.

SEE ALSO
Stdio.File->set_nonblocking and Stdio.File->set_write_callback

METHOD
Stdio.File.query_close_callback - return the close callback function

SYNTAX
function query_close_callback();

DESCRIPTION
This function returns the close_callback, which is set with set_nonblocking or set_close_callback.

SEE ALSO
Stdio.File->set_nonblocking and Stdio.File->set_close_callback

METHOD
Stdio.File.dup - duplicate a file

SYNTAX
object(Stdio.File) dup();

DESCRIPTION
This function returns a clone of Stdio.File with all variables copied from this file. Note that all variables, even id, is copied.

SEE ALSO
Stdio.File->assign

METHOD
Stdio.File.dup2 - duplicate a file over another

SYNTAX
int dup2(object(Stdio.File) to);

DESCRIPTION
This function works similarly to Stdio.File->assign, but instead of making the argument a reference to the same file, it creates a new file with the same properties and places it in the argument.

EXAMPLE
/* Redirect stdin to come from the file 'foo' */
object o=Stdio.File();
o->open("foo","r");
o->dup2(Stdio.File("stdin"));

SEE ALSO
Stdio.File->assign and Stdio.File->dup

METHOD
Stdio.File.assign - assign a file

SYNTAX
void assign(object f);

DESCRIPTION
This function takes a clone of Stdio.File and assigns all variables of this file from it. It can be used together with file->dup to move files around.

SEE ALSO
Stdio.File->dup

METHOD
Stdio.File.open_socket - open a socket

SYNTAX
int open_socket(int|void port, string|void address);

DESCRIPTION
This makes this file into a socket ready for connection. The reason for this function is so that you can set the socket to nonblocking or blocking (default is blocking) before you call Stdio.File->connect() This function returns 1 for success, 0 otherwise.

If you give a port number to this function, the socket will be bound to this port locally before connecting anywhere. This is only useful for some silly protocols like FTP. You may also specify an address to bind to if your machine has many IP numbers.

SEE ALSO
Stdio.File->connect and Stdio.File->set_nonblocking

METHOD
Stdio.File.connect - connect a socket to something

SYNTAX
int connect(string IP,int port);

DESCRIPTION
This function connects a socket previously created with Stdio.File->open_socket to a remote socket. The argument is the IP name or number for he remote machine.

This function returns 1 for success, 0 otherwise. Note that if the socket is in nonblocking mode, you have to wait for a write or close callback before you know if the connection failed or not.

SEE ALSO
Stdio.File->query_address

METHOD
Stdio.File.query_address - get addresses

SYNTAX
string query_address();
string query_address(1);

DESCRIPTION
This function returns the remote or local address of a socket on the form "x.x.x.x port". Without argument, the remote address is returned, with argument the local address is returned. If this file is not a socket, not connected or some other error occurs, zero is returned.

SEE ALSO
Stdio.File->connect

METHOD
Stdio.File.pipe - create a two-way pipe

SYNTAX
object pipe();

DESCRIPTION
This function creates a pipe between the object it was called in and an object that is returned. The two ends of the pipe are indistinguishable. If the File object this function is called in was open to begin with, it is closed before the pipe is created.

SEE ALSO
fork

METHOD
Stdio.File.set_close_on_exec - set / clear the close on exec flag

SYNTAX
void set_close_on_exec(int onoff);

DESCRIPTION
This function determines whether this file will be closed when calling exece. Default is that the file WILL be closed on exec except for stdin, stdout and stderr.

SEE ALSO
exece

Here is an example of how to use the TCP functions in Stdio.File in blocking mode. This short program takes a URL as first argument, connects to the WWW server, sends a HEAD request and writes the reply to stdout. For clarity, all calls to Stdio.File use File:: even if that is not strictly necessary.

import Stdio;
inherit File;

int main(int argc, array(string) argv)
{
    string host;
    string path="";
    int port=80;
    sscanf(argv[1],"http://%s",argv[1]);
    sscanf(argv[1],"%s/%s",host,path);
    sscanf(host,"%s:%d",host,port);

    if(!File::open_socket())
    {
        perror("Open socket failed");
        exit(1);
    }

    if(!File::connect(host,port))
    {
        perror("Failed to connect to remote host");
        exit(1);
    }

    File::write(sprintf("HEAD /%s HTTP/1.0\n",path));
    stdout::write(File::read());
}


To contents Next section