NAME
/precompiled/file - the basic file handling program

DESCRIPTION
/precompiled/file is a pre-compiled Pike program, written in C. It contains the functions needed to handle files, sockets, streams and pipes from within Pike. /precompiled/file is a part of the files module.

Here follows the descriptions of the functions in /precompiled/file:

NAME
create - init file struct

SYNTAX
object clone((program)"/precompiled/file");
or
object clone((program)"/precompiled/file",string fd);

DESCRIPTION
When cloning a file, you can specify that you want to clone stdin, stdout or stderr, by giving "stdin", "stdout" or "stderr" to clone as a second argument. If no second argument is given, an unitialized file will be cloned.

SEE ALSO
clone

NAME
open - open a file

SYNTAX
int file->open(string filename, string how);

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 close (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'.

Returns 1 on success, 0 otherwise.

SEE ALSO
file->close

NAME
close - close file

SYNTAX
int file->close(string how);
or
int file->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 funciton will not call the close_callback.

SEE ALSO
file->close

NAME
read - read data from a file or stream

SYNTAX
string file->read(int nbytes);
or
string file->read(int nbytes, int notall);

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 it's 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.

SEE ALSO
file->write

NAME
write - write data to a file or stream

SYNTAX
int file->write(string data);

DESCRIPTION
Write data to file or stream and return how many bytes that was actually written. -1 is returned if something went wrong and no bytes had been written.

SEE ALSO
file->read

NAME
seek - seek to a position in a file

SYNTAX
int file->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. Return -1 for failiure, or the old position in the file when successful.

SEE ALSO
file->tell

NAME
tell - tell where we are in a file

SYNTAX
int file->tell();

DESCRIPTION
Return the current position in the file.

SEE ALSO
file->seek

NAME
stat - do file_stat on an open file

SYNTAX
int *file->stat();

DESCRIPTION
This function returns the same information as the efun 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

NAME
errno - what was last error?

SYNTAX
int file->errno();

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

NAME
set_buffer - set internal socket buffer

SYNTAX
void file->set_buffer(int bufsize, string mode);
or
void file->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
file->open_socket and port->accept

NAME
set_nonblocking - make stream nonblocking

SYNTAX
void file->set_nonblocking(function read_callback,
function write_callback,
function close_callback);
or
void file->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. 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.

SEE ALSO
file->set_blocking

NAME
set_read_callback - set the read callback

SYNTAX
void file->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
file->set_nonblocking

NAME
set_write_callback - set the write callback

SYNTAX
void file->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
file->set_nonblocking

NAME
set_close_callback - set the close callback

SYNTAX
void file->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
file->set_nonblocking

NAME
set_blocking - make stream blocking

SYNTAX
void file->set_blocking();

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

SEE ALSO
file->set_nonblocking

NAME
set_id - set id of this file

SYNTAX
void file->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
file->query_id

NAME
query_id - get id of this file

SYNTAX
mixed file->query_id();

DESCRIPTION
This function returns the id of this file.

SEE ALSO
file->set_id

NAME
query_read_callback - return the read callback function

SYNTAX
function file->query_read_callback();

DESCRIPTION
This function returns the read_callback, which is set with file->set_nonblocking.

SEE ALSO
file->set_nonblocking

NAME
query_write_callback - return the write callback function

SYNTAX
function file->query_write_callback();

DESCRIPTION
This function returns the write_callback, which is set with file->set_nonblocking.

SEE ALSO
file->set_nonblocking

NAME
query_close_callback - return the close callback function

SYNTAX
function file->query_close_callback();

DESCRIPTION
This function returns the close_callback, which is set with file->set_nonblocking.

SEE ALSO
file->set_nonblocking

NAME
dup - duplicate a file

SYNTAX
object file->dup();

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

SEE ALSO
file->assign

NAME
dup2 - duplicate a file over another

SYNTAX
int file->dup2(object o);

DESCRIPTION
This function works similar to 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;
o=clone((program)"/precompiled/file");
o->open("foo","r");
o->dup2(clone((program)"/precompiled/file","stdin"));

SEE ALSO
file->assign and file->dup

NAME
assign - assign a file

SYNTAX
void file->assign(object f);

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

SEE ALSO
file->dup

NAME
open_socket - open a socket

SYNTAX
int file->open_socket();

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 file->connect() This function returns 1 for success, 0 otherwise.

SEE ALSO
file->connect and file->set_nonblocking

NAME
connect - connect a socket to something.

SYNTAX
int file->connect(string ip,int port);

DESCRIPTION
This funcion connects a socket previously created with file->open_socket to a remote socket. The argument is the ip name or number fot 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
file->query_address

NAME
query_address - get adresses

SYNTAX
string file->query_address();
or
string file->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
file->connect

NAME
pipe - create a two-way pipe

SYNTAX
object file->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 object is this function is called in was open to begin with, it is closed before the pipe is created.

SEE ALSO
fork

NAME
set_close_on_exec - set / clear the close on exec flag

SYNTAX
void file->set_close_on_exec(int onoff);

DESCRIPTION
This function determines weather 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