9. I/O |
CLASS Stdio.File |
This is the basic I/O object, it provides socket and pipe communication as well as file access. It does not buffer reads and writes or provide line-by-line reading, that is done with Stdio.FILE object.
The file or stream will normally be closed when this object is destructed (unless there are more objects that refer to the same file through use of assign or dup ). Objects do not contain cyclic references in themselves, so they will be destructed timely when they run out of references.
Stdio.FILE
string read()
string read(int len)
string read(int len, int(0..1) not_all)
Read data from a file or a stream.
Attempts to read len bytes from the file, and return it as a string. Less than len bytes can be returned if:
end-of-file is encountered for a normal file, or
it's a stream that has been closed from the other end, or
it's a stream in nonblocking mode, or
it's a stream and not_all is set, or
not_all isn't set and an error occurred (see below).
If not_all is nonzero, read() will not try its best to read as many bytes as you have asked for, but will merely return as much 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 not_all is used in blocking mode, read() will only block if there's no data at all available.
If something goes wrong and not_all is set, zero will be returned. If something goes wrong and not_all is zero or left out, then either zero or a string shorter than len is returned. If the problem persists then a later call to read() will fail and return zero, however.
If everything went fine, a call to errno() directly afterwards will return zero. That includes an end due to end-of-file or remote close.
If no arguments are given, read() will read to the end of the file or stream.
It's not necessary to set not_all to avoid blocking reading when nonblocking mode is used.
When at the end of a file or stream, repeated calls to read() will return the empty string since it's not considered an error. The empty string is never returned in other cases, unless nonblocking mode is used or len is zero.
read_oob() , write()
int(-1..1) peek()
int(-1..1) peek(int|float timeout)
Check if there is data available to read, or wait some time for available data to read.
Returns 1
if there is data available to read,
0
(zero) if there is no data available, and
-1
if something went wrong.
errno() , read()
The function may be interrupted prematurely of the timeout (due to signals); check the timing manually if this is imporant.
string read_oob()
string read_oob(int len)
string read_oob(int len, int(0..1) not_all)
Attempts to read len bytes of out-of-band data from the stream, and returns it as a string. Less than len bytes can be returned if:
the stream has been closed from the other end, or
nonblocking mode is used, or
not_all is set, or
not_all isn't set and an error occurred (see below).
If not_all is nonzero, read_oob() will only return as many bytes of out-of-band data as are currently available.
If something goes wrong and not_all is set, zero will be returned. If something goes wrong and not_all is zero or left out, then either zero or a string shorter than len is returned. If the problem persists then a later call to read_oob() will fail and return zero, however.
If everything went fine, a call to errno() directly afterwards will return zero. That includes an end due to remote close.
If no arguments are given, read_oob() will read to the end of the stream.
Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.
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.
It's not necessary to set not_all to avoid blocking reading when nonblocking mode is used.
When at the end of a file or stream, repeated calls to read() will return the empty string since it's not considered an error. The empty string is never returned in other cases, unless nonblocking mode is used or len is zero.
read() , write_oob()
int write(string data)
int write(string format, mixed ... extras)
int write(array(string) data)
int write(array(string) format, mixed ... extras)
Write data to a file or a stream.
Writes data and returns the number of bytes that were actually written. It can be less than the size of the given data if
some data was written successfully and then something went wrong, or
nonblocking mode is used and not all data could be written without blocking.
-1 is returned if something went wrong and no bytes were written. If only some data was written due to an error and that error persists, then a later call to write() will fail and return -1.
If everything went fine, a call to errno() directly afterwards will return zero.
If data is an array of strings, they will be written sequence.
If more than one argument is given, sprintf() will be used to format them using format . If format is an array, the strings in it are concatenated and the result is used as format string.
Writing of wide strings is not supported. You have to encode the data somehow, e.g. with string_to_utf8 or with one of the charsets supported by Locale.Charset.encoder .
read() , write_oob()
int write_oob(string data)
int write_oob(string format, mixed ... extras)
Write out-of-band data to a stream.
Writes out-of-band data to a stream and returns how many bytes that were actually written. It can be less than the size of the given data if some data was written successfully and then something went wrong.
-1 is returned if something went wrong and no bytes were written. If only some data was written due to an error and that error persists, then a later call to write_oob() will fail and return -1.
If everything went fine, a call to errno() directly afterwards will return zero.
If more than one argument is given, sprintf() will be used to format them.
Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.
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. Some streams will send the rest of the data as ordinary data.
read_oob() , write()
string grantpt()
If this file has been created by calling openpt() , return the filename of the associated pts-file. This function should only be called once.
This function is only available on some platforms.
int close()
int close(string direction)
Close a file or stream.
If direction is not specified, both the read and the write direction will be closed. Otherwise only the directions specified will be closed.
Nonzero is returned if the file or stream wasn't open in the specified direction, zero otherwise.
An exception is thrown if an I/O error occurs.
close() has no effect if this file object has been associated with an already opened file, i.e. if open() was given an integer as the first argument.
open() , open_socket()
int open(string filename, string mode)
int open(string filename, string mode, int access)
int open(int fd, string mode)
Open a file, or use an existing fd.
If filename is given, attempt to open the named file. If fd is given instead, it should be the file descriptor for an already opened file, which will then be used by this object.
mode describes how the file will be opened. It's a case-insensitive string consisting of one or more of the following letters:
Open for reading.
Open for writing.
Append new data to the end.
Create the file if it doesn't exist already.
Truncate the file to zero length if it already contains data.
Use only together with "w"
.
Open exclusively - the open will fail if the file already
exists. Use only together with "c"
. Note that it's not
safe to assume that this is atomic on some systems.
access specifies the permissions to use if a new file is created. It is a UNIX style permission bitfield:
User has read permission.
User has write permission.
User has execute permission.
Group has read permission.
Group has write permission.
Group has execute permission.
Others have read permission.
Others have write permission.
Others have execute permission.
It's system dependent on which of these bits that are actually
heeded. If access is not specified, it will default to
00666
, but note that on UNIX systems it's masked with the
process umask before use.
close()
int openpt(string mode)
Open the master end of a pseudo-terminal pair.
This function returns 1
for success, 0
otherwise.
grantpt()
int(0..1) sync()
Flush buffers to disk.
Returns 0
(zero) and sets errno on failure.
Returns 1
on success.
int seek(int pos)
int seek(int unit, int mult)
int seek(int unit, int mult, int add)
Seek to a specified offset in a file.
If mult or add are specified, pos will be calculated as
pos = unit *mult + add
.
If pos is negative it will be relative to the start of the file, otherwise it will be an absolute offset from the start of the file.
Returns the new offset, or -1
on failure.
The arguments mult and add are considered obsolete, and should not be used.
tell()
int tell()
Returns the current offset in the file.
seek()
int(0..1) truncate(int length)
Truncate a file.
Truncates the file to the specified length length .
Returns 1
on success, and 0
(zero) on failure.
open()
Stat stat()
Get status for an open file.
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, 0
(zero) will be returned. Zero is also returned if file is a pipe or
socket.
See file_stat() for a description of the return value.
Prior to Pike 7.1 this function returned an array(int).
file_stat()
int errno()
Return the errno for the latest failed file operation.
int mode()
Returns the open mode for the file.
|
open()
void set_backend(Pike.Backend backend)
Set the backend used for the callbacks.
The backend keeps a reference to this object only when it is in callback mode. So if this object hasn't got any active callbacks and it runs out of other references, it will still be destructed quickly (after closing, if necessary).
Also, this object does not keep a reference to the backend.
query_backend , set_nonblocking , set_read_callback , set_write_callback
Pike.Backend query_backend()
Return the backend used for the callbacks.
set_backend
void set_nonblocking()
Sets this file to nonblocking operation.
Nonblocking operation is not supported on all Stdio.File objects. Notably it is not guaranteed to be supported on objects returned by pipe() unless PROP_NONBLOCK was specified in the call to pipe() .
set_blocking()
void set_blocking()
Sets this file to blocking operation.
This is the inverse operation of set_nonblocking() .
set_nonblocking()
void set_close_on_exec(int(0..1) yes_no)
Marks the file as to be closed in spawned processes.
This function determines whether this file will be closed when calling exec().
Default is that the file WILL be closed on exec except for stdin, stdout and stderr.
Process.create_process() , exec()
int is_open()
Returns true if the file is open.
Most methods can't be called for a file descriptor that isn't open. Notable exceptions errno , mode , and the set and query functions for callbacks and backend.
int query_fd()
Returns the file descriptor number associated with this object.
int release_fd()
Returns the file descriptor number associated with this object, in addition to releasing it so that this object behaves as if closed. Other settings like callbacks and backend remain intact. take_fd can later be used to reinstate the file descriptor so that the state is restored.
query_fd() , take_fd()
void take_fd(int fd)
Rehooks the given file descriptor number to be associated with this object. As opposed to using open with a file descriptor number, it will be closed by this object upon destruct or when close is called.
release_fd()
void set_buffer(int bufsize, string mode)
void set_buffer(int bufsize)
Set internal socket buffer.
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.
open_socket() , accept()
Stdio.File pipe()
Stdio.File pipe(int flags)
int dup2(Stdio.File to)
Duplicate a file over another.
This function works similarly to 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.
assign() , dup()
Stdio.Fd dup()
int(0..1) open_socket(int|void port, string|void addr, int|void family)
int(0..1) set_keepalive(int(0..1) on_off)
int(0..1) connect_unix(string filename)
Open a UNIX domain socket connection to the specified destination.
In nonblocking mode, success is indicated with the write-callback, and failure with the close-callback or the read_oob-callback.
Returns 1
on success, and 0
on failure.
In nonblocking mode 0
(zero) may be returned and errno() set
to EWOULDBLOCK or WSAEWOULDBLOCK. This should not be regarded
as a connection failure.
int(0..1) connect(string dest_addr, int dest_port)
int(0..1) connect(string dest_addr, int dest_port, string src_addr, int src_port)
Open a TCP/IP connection to the specified destination.
In nonblocking mode, success is indicated with the write-callback, and failure with the close-callback or the read_oob-callback.
Returns 1
on success, and 0
on failure.
In nonblocking mode 0
(zero) may be returned and errno() set
to EWOULDBLOCK or WSAEWOULDBLOCK. This should not be regarded
as a connection failure.
string query_address()
string query_address(int(0..1) local)
Get address and port of a socket end-point.
If the argument local is not specified, or is 0
(zero),
the remote end-point will be returned. Otherwise, if local is
1
, the local end-point will be returned.
This function returns the address and port of a socket end-point
on the form "x.x.x.x port"
(IPv4) or
"x:x:x:x:x:x:x:x port"
(IPv6).
If this file is not a socket, is not connected, or some other
error occurrs, 0
(zero) will be returned.
connect()
Stdio.File `<<(string data)
Stdio.File `<<(mixed data)
Write some data to a file.
If data is not a string, it will be casted to string, and then written to the file.
Throws an error if not all data could be written.
write()
void Stdio.File(string filename)
void Stdio.File(string filename, string mode)
void Stdio.File(string filename, string mode, in access)
void Stdio.File(int fd)
void Stdio.File(int fd, string mode)
See open() .
open()
void proxy(Stdio.File from)
Starts a thread that asynchronously copies data from from to this file.
Stdio.sendfile()
Stdio.FileLockKey lock()
Stdio.FileLockKey lock(int(0..1) is_recursive)
Makes an exclusive file lock on this file.
trylock()
Stdio.FileLockKey trylock()
Stdio.FileLockKey trylock(int(0..1) is_recursive)
Attempts to place a file lock on this file.
lock()
mapping tcgetattr()
int tcsetattr(mapping attr)
int tcsetattr(mapping attr, string when)
Gets/sets term attributes. The returned value/the attr parameter is a mapping on the form
|
Negative values are not allowed as indata, but might appear in the result from tcgetattr when the actual value is unknown. tcsetattr returns 0 if failed.
The argument when to tcsetattr describes when the changes are to take effect:
|
// setting the terminal in raw mode: Stdio.stdin->tcsetattr((["ECHO":0,"ICANON":0,"VMIN":0,"VTIME":0]));
Unknown flags are ignored by tcsetattr() . tcsetattr always changes the attribute, so only include attributes that actually should be altered in the attribute mapping.
Terminal rows and columns setting by tcsetattr() is not currently supported.
inherit Fd_ref : Fd_ref
int errno()
Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.
int open(string filename, string mode)
int open(string filename, string mode, int mask)
Open a file for read, write or append. The parameter mode should contain one or more of the following letters:
|
mode should always contain at least one of the letters
"r"
or "w"
.
The parameter mask is protection bits to use if the file is
created. Default is 0666
(read+write for all in octal
notation).
This function returns 1
for success, 0
otherwise.
close() , create()
int openpt(string mode)
Open the master end of a pseudo-terminal pair. The parameter mode should contain one or more of the following letters:
|
mode should always contain at least one of the letters
"r"
or "w"
.
grantpt()
int open_socket(int|string|void port, string|void address, int|void family)
This makes this file into a socket ready for connections. The reason for this function is so that you can set the socket to nonblocking or blocking (default is blocking) before you call connect() .
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.
port can also be specified as a string, giving the name of the service associated with the port.
Finally, a protocol family for the socket can be specified. If no family is specified, one which is appropriate for the address is automatically selected. Thus, there is normally no need to specify it.
This function returns 1 for success, 0 otherwise.
connect() , set_nonblocking() , set_blocking()
int connect(string host, int|string port, void|string client, void|int|string client_port)
This function connects a socket previously created with open_socket() to a remote socket through TCP/IP. The host argument is the hostname or IP number of the remote machine. A local IP and port can be explicitly bound by specifying client and client_port .
This function returns 1 for success, 0 otherwise.
In nonblocking mode 0
(zero) may be returned and
errno() set to EWOULDBLOCK
or
WSAEWOULDBLOCK
. This should not be regarded as a
connection failure. In nonblocking mode you need to wait for a
write or close callback before you know if the connection failed
or not.
query_address() , async_connect() , connect_unix()
int connect_unix(string path)
Open a UNIX domain socket connection to the specified destination.
Returns 1
on success, and 0
on failure.
Nonblocking mode is not supported while connecting
function(:string) read_function(int nbytes)
Returns a function that when called will call read with nbytes as argument. Can be used to get various callback functions, eg for the fourth argument to String.SplitIterator .
String.SplitIterator|LineIterator line_iterator(int|void trim)
Returns an iterator that will loop over the lines in this file. If trim is true, all '\r' characters will be removed from the input.
int async_connect(string host, int|string port, function(int:void) callback, mixed ... args)
Open a TCP/IP connection asynchronously.
This function is similar to connect() , but works asynchronously.
Hostname or IP to connect to.
Port number or service name to connect to.
Function to be called on completion.
The first argument will be 1
if a connection was
successfully estabished, and 0
(zero) on failure.
The rest of the arguments to callback are passed
verbatim from args .
Extra arguments to pass to callback .
Returns 0
on failure, and 1
if callback
will be used.
The socket may be opened with open_socket() ahead of the call to this function, but it is not required.
This object is put in callback mode by this function. For callback to be called, the backend must be active. See e.g. set_read_callback for more details about backends and callback mode.
The socket will be in nonblocking state if the connection is successful, and any callbacks will be cleared.
connect() , open_socket() , set_nonblocking()
File pipe(void|int required_properties)
This function creates a pipe between the object it was called in and an object that is returned.
Binary or (predef::`|() ) of required PROP_
properties.
|
The default is PROP_NONBLOCK|PROP_BIDIRECTIONAL
.
If PROP_BIDIRECTIONAL isn't specified, the read-end is this object, and the write-end is the returned object (unless PROP_REVERSE has been specified, in which case it is the other way around).
The two ends of a bi-directional pipe are indistinguishable.
If the File object this function is called in was open to begin with, it will be closed before the pipe is created.
Calling this function with an argument of 0 is not the same as calling it with no arguments.
Process.create_process() , PROP_IPC , PROP_NONBLOCK , PROP_SHUTDOWN , PROP_BUFFERED , PROP_REVERSE , PROP_BIDIRECTIONAL
void Stdio.File()
void Stdio.File(string filename)
void Stdio.File(string filename, string mode)
void Stdio.File(string filename, string mode, int mask)
void Stdio.File(string descriptorname)
void Stdio.File(int fd)
void Stdio.File(int fd, string mode)
There are four basic ways to create a Stdio.File object. The first is calling it without any arguments, in which case the you'd have to call open() , connect() or some other method which connects the File object with a stream.
The second way is calling it with a filename and open mode . This is the same thing as cloning and then calling open() , except shorter and faster.
The third way is to call it with descriptorname of "stdin"
,
"stdout"
or "stderr"
. 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"
.
Open mode will be filtered through the system UMASK. You might need to use chmod() later.
open() , connect() , Stdio.FILE ,
int assign(File|Fd o)
This function takes a clone of Stdio.File and assigns all variables of this file from it. It can be used together with dup() to move files around.
dup()
File dup()
This function returns a clone of Stdio.File with all variables copied from this file.
All variables, even id, are copied.
assign()
int close()
int close(string direction)
Close the file. Optionally, specify "r", "w" or "rw" to close just the read, just the write or both read and write directions of the file respectively.
An exception is thrown if an I/O error occurs.
Nonzero is returned if the file wasn't open in the specified direction, zero otherwise.
This function will not call the close_callback.
open , open_socket
void set_read_callback(function(mixed:int) read_cb)
void set_write_callback(function(mixed:int) write_cb)
void set_read_oob_callback(function(mixed:int) read_oob_cb)
void set_write_oob_callback(function(mixed:int) write_oob_cb)
void set_close_callback(function(mixed:int) close_cb)
These functions set the various callbacks, which will be called when various events occur on the stream. A zero as argument will remove the callback.
A Pike.Backend object is responsible for calling the callbacks. It requires a thread to be waiting in it to execute the calls. That means that only one of the callbacks will be running at a time, so you don't need mutexes between them.
Unless you've specified otherwise with the set_backend
function, the default backend Pike.DefaultBackend will be
used. It's normally activated by returning -1
from the
main function and will then execute in the main thread.
When data arrives on the stream, read_cb will be called with some or all of that data as the second argument.
When the stream has buffer space over for writing, write_cb will be called so that you can write more data to it.
When out-of-band data arrives on the stream, read_oob_cb will be called with some or all of that data as the second argument.
When the stream allows out-of-band data to be sent, write_oob_cb will be called so that you can write more out-of-band data to it.
When the stream has been shut down, either due to an error or a close from the other end, close_cb will be called. errno will return the error that has occurred or zero in the case of a normal close. Note that close_cb will not be called for a local close, neither by a call to close or by destructing this object.
All callbacks will receive the id set by set_id as first argument.
If a callback returns -1
, no other callback or call out
will be called by the backend in that round. I.e. the caller of
the backend will get control back right away. For the default
backend that means it will immediately start another round and
check files and call outs anew.
These functions do not set the file nonblocking.
Callbacks are also set by set_nonblocking() .
After a callback has been called, it's disabled until it has accessed the stream accordingly, i.e. the write_cb callback is disabled after it's been called until something has been written with write , and the write_oob_cb callback is likewise disabled until something has been written with write_oob . Since the data already has been read when the read callbacks are called, this effect is not noticeable for them.
Installing callbacks means that you will start doing I/O on the stream from the thread running the backend. If you are running these set functions from another thread you must be prepared that the callbacks can be called immediately by the backend thread, so it might not be safe to continue using the stream in this thread.
Because of that, it's useful to talk about "callback mode" when any callback is installed. In callback mode the stream should be seen as "bound" to the backend thread. For instance, it's only the backend thread that reliably can end callback mode before the stream is "handed over" to another thread.
Callback mode has nothing to do with nonblocking mode - although the two often are used together they don't have to be.
The file object will stay referenced from the backend object as long as there are callbacks that can receive events.
Setting a close callback without a read callback currently only works when there's no risk of getting more data on the stream. Otherwise the close callback will be silently deregistered if data arrives.
set_nonblocking() , set_id() , set_backend , query_read_callback , query_write_callback , query_read_oob_callback , query_write_oob_callback , query_close_callback
function(mixed:int) query_read_callback()
function(mixed:int) query_write_callback()
function(mixed:int) query_read_oob_callback()
function(mixed:int) query_write_oob_callback()
function(mixed:int) query_close_callback()
These functions return the currently installed callbacks for the respective events.
set_nonblocking() , set_read_callback , set_write_callback , set_read_oob_callback , set_write_oob_callback , set_close_callback
void set_id(mixed id)
This function sets the id of this file. The id is mainly
used as an identifier that is sent as the first argument to all
callbacks. The default id is 0
(zero). Another possible
use of the id is to hold all data related to this file in a
mapping or array.
query_id()
mixed query_id()
This function returns the id that has been set with set_id() .
set_id()
void set_nonblocking(function(mixed:int) read_callback, function(mixed:int) write_callback, function(mixed:int) close_callback)
void set_nonblocking(function(mixed:int) read_callback, function(mixed:int) write_callback, function(mixed:int) close_callback, function(mixed:int) read_oob_callback, function(mixed:int) write_oob_callback)
void set_nonblocking()
This function sets a stream to nonblocking mode and installs the
specified callbacks. See the set_*_callback
functions
for details about them. If no arguments are given, the callbacks
will be cleared.
As opposed to calling the set callback functions separately, this function will set all the callbacks and nonblocking mode atomically so that no callback gets called in between. That avoids races in case the backend is executed by another thread.
Out-of-band data was not be supported on Pike 0.5 and earlier, and not on Pike 0.6 through 7.4 if they were compiled with the option '--without-oob'.
set_blocking() , set_read_callback() , set_write_callback() , set_read_oob_callback() , set_write_oob_callback() , set_close_callback() set_nonblocking_keep_callbacks() , set_blocking_keep_callbacks()
void set_blocking()
This function clears all callbacks and sets a stream to blocking mode. i.e. reading, writing and closing will wait until data has been transferred before returning.
The callbacks are cleared and blocking mode is set in one atomic operation, so no callback gets called in between if the backend is running in another thread.
Even so, if the stream is in callback mode (i.e. if any callbacks are installed) then only the backend thread can use this function reliably; it might otherwise already be running in a callback which is about to call e.g. write when the stream becomes blocking.
set_nonblocking() , set_nonblocking_keep_callbacks() , set_blocking_keep_callbacks()
void set_nonblocking_keep_callbacks()
void set_blocking_keep_callbacks()
Toggle between blocking and nonblocking, without changing the callbacks.
set_nonblocking() , set_blocking()
CLASS Stdio.FILE |
Stdio.FILE is a buffered version of Stdio.File , it inherits Stdio.File and has most of the functionality of Stdio.File . However, it has an input buffer that allows line-by-line input.
It also has support for automatic charset conversion for both input and output (see Stdio.FILE()->set_charset() ).
The output part of Stdio.FILE is currently not buffered.
inherit File : file
void set_charset(string charset)
Sets the input and output charset of this file to the specified charset .
The default charset is "ISO-8859-1".
string gets()
Read one line of input with support for input conversion.
This function returns the line read if successful, and 0
if
no more lines are available.
ngets() , read() , line_iterator() , set_charset()
array(string) ngets(void|int(1..) n)
Get n lines.
Number of lines to get, or all remaining if zero.
File pipe(void|int flags)
Same as Stdio.File()->pipe() .
Returns an Stdio.File object, NOT a Stdio.FILE object.
int write(array(string)|string what, mixed ... fmt)
Write what with support for output_conversion.
Stdio.File()->write()
int printf(string format, mixed ... data)
This function does approximately the same as:
write (sprintf (format ,@data ))
.
write() , sprintf()
object _get_iterator()
Returns an iterator that will loop over the lines in this file.
line_iterator()
object line_iterator(int|void trim)
Returns an iterator that will loop over the lines in this file. If trim is true, all '\r' characters will be removed from the input.
_get_iterator()
string read(int|void bytes, void|int(0..1) now)
Read bytes (wide-) characters with buffering and support for input conversion.
Stdio.File()->read() , set_charset()
void ungets(string s)
This function puts a string back in the input buffer. The string can then be read with eg read() , gets() or getchar() .
The string must not contain line-feeds.
read() , gets() , getchar()
int getchar()
This function returns one character from the input stream.
Returns the ISO-10646 (Unicode) value of the character.
Returns an int
and not a string
of length 1.
CLASS Stdio.Port |
Handles listening to socket ports. Whenever you need a bound socket that is open and listens for connections you should use this program.
mixed set_id(mixed id)
This function sets the id used for accept_callback by this port. The default id is this_object() .
query_id
mixed query_id()
This function returns the id for this port. The id is normally the first argument to accept_callback.
set_id
int errno()
If the last call done on this port failed, errno will return an integer describing what went wrong. Refer to your unix manual for further information.
int listen_fd(int fd, void|function accept_callback)
This function does the same as port->bind, except that instead of creating a new socket and bind it to a port, it expects that the filedescriptor 'fd' is an already open port.
This function is only for the advanced user, and is generally used when sockets are passed to Pike at exec time.
bind , accept
int bind(int|string port, void|function accept_callback, void|string ip)
Bind opens a socket and binds it to port number on the local machine. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument. Bind returns 1 on success, and zero on failiure.
If the optional argument 'ip' is given, bind will try to bind to this ip name or number.
accept
int bind_unix(string path, void|function accept_callback)
Bind opens a Unix domain socket at the filesystem location path. If the second argument is present, the socket is set to nonblocking and the callback funcition is called whenever something connects to it. The callback will receive the id for this port as argument.
1 on success, and zero on failiure.
this function is only available on systems that support Unix domain sockets.
accept
void close()
Closes the socket.
Stdio.File accept()
string query_address(string arg1)
Document this function.
void set_backend(Pike.Backend backend)
Set the backend used for the accept callback.
The backend keeps a reference to this object as long as the port is accepting connections, but this object does not keep a reference to the backend.
query_backend
Pike.Backend query_backend()
Return the backend used for the accept callback.
set_backend
inherit _port : _port
void Stdio.Port()
void Stdio.Port(int|string port)
void Stdio.Port(int|string port, function accept_callback)
void Stdio.Port(int|string port, function accept_callback, string ip)
void Stdio.Port("stdin")
void Stdio.Port("stdin", function accept_callback)
If the first argument is other than "stdin"
the arguments will
be passed to bind() .
When create is called with "stdin"
as the first argument, a
socket is created out of the file descriptor 0
. This is only
useful if it actually is a socket to begin with.
bind
File accept()
This function completes a connection made from a remote machine to this port. It returns a two-way stream in the form of a clone of Stdio.File . The new file is by initially set to blocking mode.
Stdio.File
CLASS Stdio.UDP |
UDP (User Datagram Protocol) handling.
int(0..1) close()
Closes an open UDP port.
This method was introduced in Pike 7.5.
object bind(int|string port)
object bind(int|string port, string address)
Binds a port for recieving or transmitting UDP.
int(0..1) enable_broadcast()
Set the broadcast flag. If enabled then sockets receive packets sent to a broadcast address and they are allowed to send packets to a broadcast address.
Returns 1
on success, 0
(zero) otherwise.
This is normally only avalable to root users.
int(0..1) wait(int|float timeout)
Check for data and wait max. timeout seconds.
Returns 1
if data are ready, 0
(zero) otherwise.
mapping(string:int|string) read()
mapping(string:int|string) read(int flag)
Read from the UDP socket.
Flag flag is a bitfield, 1 for out of band data and 2 for peek
mapping(string:int|string) in the form ([ "data" : string received data "ip" : string received from this ip "port" : int ...and this port ])
set_read_callback()
int send(string to, int|string port, string message)
int send(string to, int|string port, string message, int flags)
Send data to a UDP socket. The recepient address will be to and port will be port .
Flag flag is a bitfield, 1 for out of band data and 2 for don't route flag.
The number of bytes that were actually written.
object set_blocking()
Sets this object to be blocking.
int(0..1) connect(string address, int|string port)
Establish an UDP connection.
This function connects an UDP socket previously created with Stdio.UDP() to a remote socket. The address is the IP name or number for the remote machine.
Returns 1
on success, 0
(zero) otherwise.
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.
bind() , query_address()
string query_address()
Returns the local address of a socket on the form "x.x.x.x port". If this file is not a socket, not connected or some other error occurs, zero is returned.
void set_backend(Pike.Backend backend)
Set the backend used for the read callback.
The backend keeps a reference to this object as long as there can be calls to the read callback, but this object does not keep a reference to the backend.
query_backend
Pike.Backend query_backend()
Return the backend used for the read callback.
set_backend
int errno()
Returns the error code for the last command on this object. Error code is normally cleared when a command is successful.
object set_type(int sock_type)
object set_type(int sock_type, int family)
Sets socket type and protocol family.
array(int) get_type()
Returns socket type and protocol family.
constant MSG_OOB
Document this constant.
constant MSG_PEEK
Document this constant.
inherit files.UDP : UDP
UDP set_nonblocking()
UDP set_nonblocking(function(mapping(string:int|string):void) read_cb, mixed ... extra_args)
Set this object to nonblocking mode.
If read_cb and extra_args are specified, they will be passed on to set_read_callback() .
The called object.
UDP set_read_callback(function(mapping(string:int|string):) read_cb, mixed ... extra_args)
The read_cb function will receive a mapping similar to the mapping returned by read() :
|
The called object.
read()
Module Stdio.Terminfo |
Termcap Stdio.Terminfo.getTermcap(string term)
Returns the terminal description object for term from the systems termcap database. Returns 0 if not found.
Stdio.Terminfo.getTerm, Stdio.Terminfo.getTerminfo
Terminfo Stdio.Terminfo.getTerminfo(string term)
Returns the terminal description object for term from the systems terminfo database. Returns 0 if not found.
Stdio.Terminfo.getTerm, Stdio.Terminfo.getTermcap
Termcap Stdio.Terminfo.getTerm(string|void term)
Returns an object describing the terminal term. If term is not specified, it will default to getenv("TERM") or if that fails to "dumb".
Lookup of terminal information will first be done in the systems terminfo database, and if that fails in the termcap database. If neither database exists, a hardcoded entry for "dumb" will be used.
Stdio.Terminfo.getTerminfo, Stdio.Terminfo.getTermcap, Stdio.getFallbackTerm
Termcap Stdio.Terminfo.getFallbackTerm(string term)
Returns an object describing the fallback terminal for the terminal term . This is usually equvivalent to Stdio.Terminfo.getTerm("dumb") .
Stdio.Terminfo.getTerm
int Stdio.Terminfo.is_tty()
Returns 1 if Stdio.stdin is connected to an interactive terminal that can handle backspacing, carriage return without linefeed, and the like.
CLASS Stdio.Terminfo.Termcap |
Termcap terminal description object.
inherit TermMachine : TermMachine
array(string) aliases
string tputs(string s)
Put termcap string
void Stdio.Terminfo.Termcap(string cap, TermcapDB|void tcdb, int|void maxrecurse)
CLASS Stdio.Terminfo.Terminfo |
Terminfo terminal description object
inherit TermMachine : TermMachine
array(string) aliases
string tputs(string s)
Document this function
void Stdio.Terminfo.Terminfo(string filename)
CLASS Stdio.Readline |
OutputController get_output_controller()
get current output control object
Terminal output controller object
InputController get_input_controller()
get current input control object
Terminal input controller object
string get_prompt()
Return the current prompt string.
string set_prompt(string newp, array(string)|void newattrs)
Set the prompt string.
New prompt string
Terminal attributes
void set_echo(int onoff)
Set text echo on or off.
1 for echo, 0 for no echo.
string gettext()
Document this function
int getcursorpos()
Document this function
int setcursorpos(int p)
Document this function
int setmark(int p)
Document this function
int getmark()
Document this function
void insert(string s, int p)
Document this function
void delete(int p1, int p2)
Document this function
array(int) pointmark()
Document this function
string region(int ... args)
Document this function
void kill(int p1, int p2)
Document this function
void add_to_kill_ring(string s)
Document this function
string kill_ring_yank()
Document this function
void history(int n)
Document this function
void delta_history(int d)
Changes the line to a line from the history d steps from the current entry (0 being the current line, negative values older, and positive values newer).
Only effective if you have a history object.
void redisplay(int clear, int|void nobackup)
Document this function
string newline()
Document this function
void eof()
Document this function
void message(string msg)
Print a message to the output device
void write(string msg, void|int word_wrap)
Document this function
void list_completions(array(string) c)
Document this function
void set_nonblocking(function f)
Document this function
void set_blocking()
Document this function
string edit(string data, string|void local_prompt, array(string)|void attrs)
Document this function
string read(string|void prompt, array(string)|void attrs)
Document this function
void enable_history(array(string)|History|int hist)
Document this function
History get_history()
Document this function
void Stdio.Readline(object|void infd, object|string|void interm, object|void outfd, object|string|void outterm)
Creates a Readline object, that takes input from infd and has output on outfd .
Defaults to Stdio.stdin .
Defaults to Stdio.Terminfo.getTerm() .
Defaults to infd , unless infd is 0, in which case outfd defaults to Stdio.stdout .
Defaults to interm .
CLASS Stdio.Readline.OutputController |
Ought to have support for charset conversion.
void turn_on(string ... atts)
Set the provided attributes to on.
void turn_off(string ... atts)
Set the provided attributes to off.
void disable()
void enable()
int check_columns()
Check and return the terminal width.
In Pike 7.4 and earlier this function returned void
.
get_number_of_columns
int get_number_of_columns()
Returns the width of the terminal.
Does not check the width of the terminal.
check_columns
void low_write(string s, void|int word_break)
void write(string s, void|int word_break, void|int hide)
void low_move_downward(int n)
void low_move_upward(int n)
void low_move_forward(int n)
void low_move_backward(int n)
void low_erase(int n)
void move_forward(string s)
void move_backward(string s)
void erase(string s)
void newline()
void bol()
void clear(int|void partial)
void beep()
void Stdio.Readline.OutputController(.File|void _outfd, .Terminfo.Termcap|string|void _term)
CLASS Stdio.Readline.InputController |
Ought to have support for charset conversion.
int isenabled()
int enable(int ... e)
int disable()
int run_blocking()
void set_close_callback(function(:int) ccb)
void nullbindings()
Clears the bindings.
void grabnextkey(function g)
function bindstr(string str, function f)
function unbindstr(string str)
function getbindingstr(string str)
function bindtc(string cap, function f)
function unbindtc(string cap)
function getbindingtc(string cap)
string parsekey(string k)
function bind(string k, function f)
function unbind(string k)
function getbinding(string k, string cap)
mapping(string:function) getbindings()
void Stdio.Readline.InputController(object|void _infd, object|string|void _term)
CLASS Stdio.Readline.DefaultEditKeys |
void self_insert_command(string str)
void quoted_insert()
void newline()
void up_history()
void down_history()
void backward_delete_char()
void delete_char_or_eof()
void forward_char()
void backward_char()
void beginning_of_line()
void end_of_line()
void transpose_chars()
void capitalize_word()
void upcase_word()
void downcase_word()
void forward_word()
void backward_word()
void kill_word()
void backward_kill_word()
void kill_line()
void kill_whole_line()
void yank()
void kill_ring_save()
void kill_region()
void set_mark()
void swap_mark_and_point()
void redisplay()
void clear_screen()
void set_default_bindings()
void Stdio.Readline.DefaultEditKeys(object readline)
CLASS Stdio.Readline.History |
string encode()
int get_history_num()
string history(int n, string text)
void initline()
void finishline(string text)
void set_max_history(int maxhist)
void Stdio.Readline.History(int maxhist, void|array(string) hist)
Module Stdio |
array(int) Stdio.get_all_active_fd()
Returns the id of all the active file descriptors.
void Stdio.notify(void|int notification, function(void:void) callback)
Receive notification when change occur within the fd. To use, create a Stdio.File object of a directory like Stdio.File(".") and then call notify() with the appropriate parameters.
When a program registers for some notification, only the first notification will be received unless DN_MULTISHOT is specified as part of the notification argument.
At present, this function is Linux-specific and requires a kernel which supports the F_NOTIFY fcntl() call.
What to notify the callback of. See the Stdio.DN_* constants for more information about possible notifications.
Function which should be called when notification is received. The function gets the signal used to indicate the notification as its argument and shouldn't return anyting.
constant Stdio.PROP_BIDIRECTIONAL
Document this constant.
constant Stdio.PROP_BUFFERED
Document this constant.
constant Stdio.PROP_SHUTDOWN
Document this constant.
constant Stdio.PROP_NONBLOCK
Document this constant.
constant Stdio.PROP_REVERSE
Document this constant.
constant Stdio.PROP_IPC
Document this constant.
constant Stdio.IPPROTO
Document this constant.
constant Stdio.__OOB__
Implementation level of nonblocking I/O OOB support.
|
This constant only exists when OOB operations are available, i.e. when __HAVE_OOB__ is 1.
constant Stdio.__HAVE_OOB__
Exists and has the value 1 if OOB operations are available.
In Pike 7.5 and later OOB operations are always present.
string Stdio._sprintf(int type, void|mapping flags)
constant Stdio.DN_ACCESS
Used in File.notify() to get a callback when files within a directory are accessed.
constant Stdio.DN_MODIFY
Used in File.notify() to get a callback when files within a directory are modified.
constant Stdio.DN_CREATE
Used in File.notify() to get a callback when new files are created within a directory.
constant Stdio.DN_DELETE
Used in File.notify() to get a callback when files are deleted within a directory.
constant Stdio.DN_RENAME
Used in File.notify() to get a callback when files within a directory are renamed.
constant Stdio.DN_ATTRIB
Used in File.notify() to get a callback when attributes of files within a directory are changed.
constant Stdio.DN_MULTISHOT
Used in File.notify() . If DN_MULTISHOT is used, signals will be sent for all notifications the program has registred for. Otherwise only the first event the program is listening for will be received and then the program must reregister for the events to receive futher events.
inherit files : files
File Stdio.stderr
An instance of FILE("stderr"), the standard error stream. Use this when you want to output error messages.
predef::werror()
File Stdio.stdout
An instance of FILE("stdout"), the standatd output stream. Use this when you want to write anything to the standard output.
predef::write()
FILE Stdio.stdin
An instance of FILE("stdin"), the standard input stream. Use this when you want to read anything from the standard input. This example will read lines from standard input for as long as there are more lines to read. Each line will then be written to stdout together with the line number. We could use Stdio.stdout.write() instead of just write() , since they are the same function.
int main() { int line; while(string s=Stdio.stdin.gets()) write("%5d: %s\n", line++, s); }
string Stdio.read_file(string filename)
string Stdio.read_file(string filename, int start, int len)
Read len lines from a file filename after skipping start lines and return those lines as a string. If both start and len are omitted the whole file is read.
read_bytes() , write_file()
string Stdio.read_bytes(string filename, int start, int len)
string Stdio.read_bytes(string filename, int start)
string Stdio.read_bytes(string filename)
Read len number of bytes from the file filename starting at byte start , and return it as a string.
If len is omitted, the rest of the file will be returned.
If start is also omitted, the entire file will be returned.
Throws an error if filename isn't a regular file.
Returns 0
(zero) on failure to open filename .
Returns a string with the requested data otherwise.
read_file , write_file() , append_file()
int Stdio.write_file(string filename, string str, int|void access)
Write the string str onto the file filename . Any existing data in the file is overwritten.
For a description of access , see Stdio.File()->open() .
Throws an error if filename couldn't be opened for writing.
Returns the number of bytes written.
append_file() , read_bytes() , Stdio.File()->open()
int Stdio.append_file(string filename, string str, int|void access)
Append the string str onto the file filename .
For a description of access , see Stdio.File->open() .
Throws an error if filename couldn't be opened for writing.
Returns the number of bytes written.
write_file() , read_bytes() , Stdio.File()->open()
int Stdio.file_size(string filename)
Give the size of a file. Size -1 indicates that the file either does not exist, or that it is not readable by you. Size -2 indicates that it is a directory.
file_stat() , write_file() , read_bytes()
string Stdio.append_path(string absolute, string ... relative)
Append relative paths to an absolute path and remove any
"//"
, "../"
or "/."
to produce a
straightforward absolute path as a result.
"../"
is ignorded in the relative paths if it makes the
created path begin with something else than the absolute path
(or so far created path).
Warning: This does not work on NT. (Consider paths like: k:/fnord)
combine_path()
string Stdio.simplify_path(string path)
Returns a canonic representation of path (without /./, /../, // and similar path segments).
void Stdio.perror(string s)
This function prints a message to stderr along with a description of what went wrong if available. It uses the system errno to find out what went wrong, so it is only applicable to IO errors.
werror()
int Stdio.is_file(string path)
Check if a path is a file.
Returns true if the given path is a file, otherwise false.
exist() , is_dir() , is_link() , file_stat()
int Stdio.is_dir(string path)
Check if a path is a directory.
Returns true if the given path is a directory, otherwise false.
exist() , is_file() , is_link() , file_stat()
int Stdio.is_link(string path)
Check if a path is a symbolic link.
Returns true if the given path is a symbolic link, otherwise false.
exist() , is_dir() , is_file() , file_stat()
int Stdio.exist(string path)
Check if a path exists.
Returns true if the given path exists (is a directory or file), otherwise false.
is_dir() , is_file() , is_link() , file_stat()
int Stdio.cp(string from, string to)
Copies the file from to the new position to . If there is no system function for cp, a new file will be created and the old one copied manually in chunks of 65536 bytes.
int Stdio.file_equal(string file_1, string file_2)
Returns nonzero if the given paths are files with identical content, returns zero otherwise. Zero is also returned for any sort of I/O error.
void Stdio.async_cp(string from, string to, function(int:void) callback, mixed ... args)
Copy a file asynchronously.
This function is similar to cp() , but works asynchronously.
Name of file to copy.
Name of file to create or replace with a copy of from .
Function to be called on completion.
The first argument will be 1
on success, and 0
(zero)
otherwise. The rest of the arguments to callback are passed
verbatim from args .
Extra arguments to pass to callback .
For callback to be called, the backend must be active (ie
main() must have returned -1
, or Pike.DefaultBackend
get called in some other way). The actual copying may start
before the backend has activated.
Currently the file sizes are not compared, so the destination file (to ) may be truncated.
cp() , sendfile()
int Stdio.mkdirhier(string pathname, void|int mode)
Creates zero or more directories to ensure that the given pathname is a directory.
If a mode is given, it's used for the new directories after being &'ed with the current umask (on OS'es that support this).
Returns zero on failure and nonzero on success.
mkdir()
int Stdio.recursive_rm(string path)
Remove a file or directory a directory tree.
Returns 0 on failure, nonzero otherwise.
rm
object Stdio.sendfile(array(string) headers, File from, int offset, int len, array(string) trailers, File to)
object Stdio.sendfile(array(string) headers, File from, int offset, int len, array(string) trailers, File to, function(int:void) callback, mixed ... args)
Sends headers followed by len bytes starting at offset from the file from followed by trailers to the file to . When completed callback will be called with the total number of bytes sent as the first argument, followed by args .
Any of headers , from and trailers may be left out
by setting them to 0
.
Setting offset to -1
means send from the current position in
from .
Setting len to -1
means send until from 's end of file is
reached.
The sending is performed asynchronously, and may complete before or after the function returns.
For callback to be called, the backend must be active (ie
main() must have returned -1
, or Pike.DefaultBackend
get called in some other way).
In some cases, the backend must also be active for any sending to be performed at all.
FIXME: Support for timeouts?
Stdio.File->set_nonblocking()
void Stdio.werror(string s)
Write a message to stderr. Stderr is normally the console, even if the process output has been redirected to a file or pipe.
This function is identical to predef::werror() .
predef::werror()
CLASS Stdio.Fd_ref |
Proxy class that contains stub functions that call the corresponding functions in Fd .
Used by File .
Fd _fd
Object to which called functions are relayed.
CLASS Stdio.Fd |
Low level I/O operations. Use File instead.
CLASS Stdio.Stat |
This object is used to represent file status information from e.g. file_stat() .
It contains the following items usually found in a C struct stat:
File mode (see mknod(2)).
File size in bytes.
User ID of the file's owner.
Group ID of the file's owner.
Time of last access in seconds since 00:00:00 UTC, 1970-01-01.
Time of last data modification.
Time of last file status change.
Inode number.
Number of links.
ID of the device containing a directory entry for this file.
ID of the device.
It also contains some items that correspond to the C IS* macros:
Set if the file is a regular file.
Set if the file is a directory.
Set if the file is a symbolic link. Note that symbolic links are normally followed by the stat functions, so this might only be set if you turn that off, e.g. by giving a nonzero second argument to file_stat() .
Set if the file is a FIFO (aka named pipe).
Set if the file is a socket.
Set if the file is a character device.
Set if the file is a block device.
There are also some items that provide alternative representations of the above:
The type as a string, can be any of "reg"
,
"dir"
, "lnk"
, "fifo"
, "sock"
,
"chr"
, "blk"
, and "unknown"
.
The file mode encoded as a string in ls -l style, e.g.
"drwxr-xr-x"
.
Note that some items might not exist or have meaningful values on some platforms.
Additionally, the object may be initialized from or casted to an
array
on the form of a 'traditional' LPC stat-array, and
it's also possible to index the object directly with integers as
if it were such an array. The stat-array has this format:
|
It's possible to modify the stat struct by assigning values to
the items. They essentially work as variables, although some of
them affect others, e.g. setting isdir
clears isreg
and setting mode_string
changes many of the other items.
void Stdio.Stat(void|object|array stat)
A new Stdio.Stat object can be initialized in two ways:
stat is an object, typically another Stdio.Stat . The
stat info is copied from the object by getting the values of
mode
, size
, atime
, mtime
,
ctime
, uid
, gid
, dev
, ino
,
nlink
, and rdev
.
stat is a seven element array on the 'traditional' LPC stat-array form (see the class doc).
CLASS Stdio.FakeFile |
A string wrapper that pretends to be a Stdio.File object.
constant is_fake_file
This constant can be used to distinguish a FakeFile object from a real Stdio.File object.
int close(void|string direction)
Stdio.File()->close()
void Stdio.FakeFile(string data, void|string type, void|int pointer)
Stdio.File()->create()
this_program dup()
Stdio.File()->dup()
int errno()
Always returns 0.
Stdio.File()->errno()
String.SplitIterator line_iterator(int|void trim)
Stdio.File()->line_iterator()
mixed query_id()
Stdio.File()->query_id()
void set_id(mixed _id)
Stdio.File()->set_id()
function(:string) read_function(int nbytes)
Stdio.File()->read_function()
int(-1..1) peek(int|float|void timeout)
Stdio.File()->peek()
string query_address(void|int(0..1) is_local)
Always returns 0.
Stdio.File()->query_address()
string read(void|int(0..) len, void|int(0..1) not_all)
Stdio.File()->read()
int seek(int pos, void|int mult, void|int add)
Stdio.File()->seek()
int(1..1) sync()
Always returns 1.
Stdio.File()->sync()
int tell()
Stdio.File()->tell()
int(0..1) truncate(int length)
Stdio.File()->truncate()
int(-1..) write(string|array(string) str, mixed ... extra)
Stdio.File()->write()
mixed cast(string to)
A FakeFile can be casted to a string.
int(0..) _sizeof()
Sizeof on a FakeFile returns the size of its contents.
CLASS Stdio.Stream |
The Stdio.Stream API.
This class exists purely for typing reasons.
Use in types in place of Stdio.File where only blocking stream-oriented I/O is done with the object.
NonblockingStream , BlockFile , File , FILE
CLASS Stdio.NonblockingStream |
The Stdio.NonblockingStream API.
This class exists purely for typing reasons.
Use in types in place of Stdio.File where nonblocking and/or blocking stream-oriented I/O is done with the object.
Stream , BlockFile , File , FILE
inherit Stream : Stream
CLASS Stdio.BlockFile |
The Stdio.BlockFile API.
This class exists purely for typing reasons.
Use in types in place of Stdio.File where only blocking I/O is done with the object.
Stream , NonblockingStream , File , FILE
inherit Stream : Stream