uLPC v1.0E-8 Reference Manual: /precompiled/file

NAME

/precompiled/file - the basic file handling program

DESCRIPTION

/precompiled/file is a pre-compiled LPC program, written in C. It contains the functions need to handle files, sockets, streams and pipes from within lpc. /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", "stdou" or "stderr" to clone as a second argument. If no second argument is given, an unitialized file will be cloned.
SEE ALSO

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

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

NAME: read - read data from a file or stream
SYNTAX: string file->read(int nbytes);
DESCRIPTION: Read tries to read nbytes bytes from the file, and return it as a string. If something goes wrong, zero is returned.
SEE ALSO

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

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

NAME: tell - tell where we are in a file
SYNTAX: int file->tell();
DESCRIPTION: Return the current position in the file.
SEE ALSO

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

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

NAME

set_nonblocking - make stream nonblocking

SYNTAX

void file->set_nonblocking( function read_callback, function write_callback, function close_callback);

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.

SEE ALSO

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

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

NAME: query_id - get id of this file
SYNTAX: mixed file->query_id();
DESCRIPTION: This function returns the id of this file.
SEE ALSO

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

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

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

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

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

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

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

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 remot 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

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

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