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
	builtin/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, 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, 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, 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
	builtin/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
	builtin/exece

============================================================================
