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
void receive_fd(Stdio.Fd fd)
Remote file descriptor reception handler.
File descriptor received from the remote end of a pipe() . This object has been created by fd_factory() .
This function is called from read() when a remote file descriptor has been received over a PROP_SEND_FD capable pipe() .
The default implementation is just a prototype.
Overload this function to enable reception of remote file descriptors.
The capability of sending and receiving remote file descriptors is only available on some operating systems. This capability is indicated by the precence of __HAVE_SEND_FD__ .
send_fd() , read() , fd_factory() , __HAVE_SEND_FD__
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() does not try its best to read as many bytes as you have asked for, but merely returns as much as the system read function returns. This is 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() only blocks if there's no data at all available.
If something goes wrong and not_all is set, zero is 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() fails and returns zero, however.
If everything went fine, a call to errno() directly afterwards returns zero. That includes an end due to end-of-file or remote close.
If no arguments are given, read() reads to the end of the file or stream.
If any file descriptors have been sent by the other side of the stream, receive_fd() will be called once for every sent file descriptor.
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() , receive_fd() , send_fd()
int(-1..1) peek()
int(-1..1) peek(int|float timeout)
int(-1..1) peek(int|float timeout, int not_eof)
Check if there is data available to read, or wait some time for available data to read.
More specifically, a later call to read() will return immediately, either due to data being present, or due to some error (eg if a socket has been closed).
Timeout in seconds.
Flag for specifying handling of end of file. The following values are currently defined:
|
|
errno() , read()
The function may be interrupted prematurely of the timeout (due to signals); check the timing manually if this is imporant.
The not_eof parameter was added in Pike 7.7.
This function was not available on NT in Pike 7.6 and earlier.
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() only returns as many bytes of out-of-band data as are currently available.
If something goes wrong and not_all is set, zero is 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() fails and returns zero, however.
If everything went fine, a call to errno() directly afterwards returns zero. That includes an end due to remote close.
If no arguments are given, read_oob() reads to the end of the stream.
Out-of-band data was not supported in Pike 0.5 and earlier, and not in 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 is 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() returns 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() fails and returns -1.
If everything went fine, a call to errno() directly afterwards returns zero.
If data is an array of strings, they are written in sequence.
If more than one argument is given, sprintf() is 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.
If there are any file descriptors that have been queued for sending (with send_fd() ), they will be sent.
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() , send_fd()
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() fails and returns -1.
If everything went fine, a call to errno() directly afterwards returns zero.
If more than one argument is given, sprintf() is used to format them.
Out-of-band data was not supported in Pike 0.5 and earlier, and not in 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 is received. Most streams only allow for a single byte of out-of-band data at a time. Some streams sends the rest of the data as ordinary data.
read_oob() , write()
void send_fd(Stdio.Fd fd)
Queues an open file descriptor for sending to the other end of a stream.
The actual sending is performed at the next successful call to write() , this is due to limitations in the system calls. This means that it isn't possible to send a file descriptor without also sending some in-band data.
This operation is only supported on pipe() 's created with PROP_SEND_FD .
This function is not available on all operating systems, check for __HAVE_SEND_FD__ .
The queue is emptied on successful write() and when the write direction is close() 'd.
receive_fd() , write() , pipe() , read() , __HAVE_SEND_FD__
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 is closed. Otherwise only the directions specified is 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 is 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 fails 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 defaults to
00666
, but note that on UNIX systems it's masked with the
process umask before use.
Returns nonzero on success and 0
(zero) on failure. If
there is a failure then errno returns the error code.
close()
Stdio.File openat(string filename, string mode)
Stdio.File openat(string filename, string mode, int access)
Open a file relative to an opened directory.
Returns a new file object on success, and 0
(zero) on failure.
Not available on all architectures, or in Pike 7.6 and earlier.
open() , statat() , unlinkat()
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 is calculated as
pos = unit *mult + add
.
If pos is negative then it is relative to the end of the file, otherwise it's 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) is 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() , statat()
Stat statat(string path, void|int(0..1) symlink)
Get status for a file relative an open directory.
This function returns the same information as the function
file_stat() , but relative to the file it is called in. If file is not
an open file, 0
(zero) is returned. Zero is also returned
if file is a pipe or socket.
See file_stat() for a description of the return value.
Not available on all architectures, or in Pike 7.6 and earlier.
file_stat() , stat() , openat() , unlinkat()
int unlinkat(string f)
Remove a file or directory relative to an open file.
Returns 0
(zero) on failure, 1
otherwise.
rm() , openat() , statat()
array(string) listxattr()
Return an array of all extended attributes set on the file
string getxattr(string attr)
Return the value of a specified attribute, or 0 if it does not exist
void removexattr(string attr)
Remove the specified extended attribute.
void setxattr(string attr, string value, int flags)
Set the attribute attr to the value value .
The flags parameter can be used to refine the semantics of the operation.
Stdio.XATTR_CREATE specifies a pure create, which fails if the named attribute exists already.
Stdio.XATTR_REPLACE specifies a pure replace operation, which fails if the named attribute does not already exist.
By default (no flags), the extended attribute will be created if need be, or will simply replace the value if the attribute exists.
1 if successful, 0 otherwise, setting errno.
int errno()
Return the errno for the latest failed file operation.
int mode()
Returns the open mode and capabilities for the file.
Returns an `|() of the following flags:
|
In some versions of Pike 7.7 and 7.8 the PROP_ flags were filtered from the result.
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.
If the file is a socket that has been closed from the remote side, this function might still return true.
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.
Returns 1
on success and 0
(zero) on failure.
In Pike 7.7 and later to need not be open, in which case a new fd is allocated.
Note also that to is also assigned to the same backend (if any) as this object.
assign() , dup()
Stdio.Fd dup()
Duplicate the file.
dup2()
int(0..1) open_socket(int|void port, string|void addr, int|string|void family_hint)
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.
Filename to create.
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.
path had a quite restrictive length limit (~100 characters) prior to Pike 7.8.334.
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 is returned. Otherwise, if local
is 1
, the local end-point is 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). IPv6 addresses
may use the contracted syntax.
If this file is not a socket, is not connected, or some other
error occurs, 0
(zero) is returned and errno() will
return the error code.
An error is thrown if the socket (or file) isn't open.
connect()
Stdio.File `<<(string data)
Stdio.File `<<(mixed data)
Write some data to a file.
If data is not a string, it is 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, int 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()
void 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.
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
inherit Fd : Fd
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|string|void family_hint)
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. The port can also be specified as a string, giving the name of the service associated with the port.
You may specify an address to bind to if your machine has many IP numbers.
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. If you do not want to specify a bind address, you can provide the address as a hint here instead, to allow the automatic selection to work anyway.
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() , send_fd() , receive_fd() , PROP_IPC , PROP_NONBLOCK , PROP_SEND_FD , PROP_SHUTDOWN , PROP_BUFFERED , PROP_REVERSE , PROP_BIDIRECTIONAL
File openat(string filename, string mode)
File openat(string filename, string mode, int mask)
Open a file relative to an open directory.
File.statat() , File.unlinkat()
int(0..1) send_fd(File|Fd file)
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.
This callback is also called after the remote end of a socket connection has closed the write direction. An attempt to write data to it in that case will generate a System.EPIPE errno. If the remote end has closed both directions simultaneously (the usual case), Pike will first attempt to call close_cb , then this callback (unless close_cb has closed the stream).
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.
If the OS doesn't separate the write events for normal and out-of-band data, Pike will try to call write_oob_cb first. If it doesn't write anything, then write_cb will be tried. This also means that write_oob_cb might get called when the remote end of a connection has closed the write direction.
When an error or an end-of-stream in the read direction occurs, close_cb will be called. errno will return the error, or zero in the case of an end-of-stream.
The name of this callback is rather unfortunate since it really has nothing to do with a close: The stream is still open when close_cb is called (you might not be able to read and/or write to it, but you can still use things like query_address , and the underlying file descriptor is still allocated). Also, this callback will not be called for a local close, neither by a call to close or by destructing this object.
Also, close_cb will not be called if a remote close only occurs in the write direction; that is handled by write_cb (or possibly write_oob_cb ).
Events to read_cb and close_cb will be automatically deregistered if an end-of-stream occurs, and all events in the case of an error. I.e. there won't be any more calls to the callbacks unless they are reinstalled. This doesn't affect the callback settings - query_read_callback et al will still return the installed callbacks.
If the stream is a socket performing a nonblocking connect (see open_socket and connect ), a connection failure will call close_cb , and a successful connect will call either read_cb or write_cb as above.
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_callbacks and 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_callbacks , set_nonblocking() , set_id() , set_backend , query_read_callback , query_write_callback , query_read_oob_callback , query_write_oob_callback , query_close_callback
void set_callbacks(void|function(mixed:int) read_cb, void|function(mixed:int) write_cb, void|function(mixed:int) close_cb, void|function(mixed:int) read_oob_cb, void|function(mixed:int) write_oob_cb)
Installs all the specified callbacks at once. Use UNDEFINED to keep the current setting for a callback.
Like set_nonblocking , the callbacks are installed atomically. As opposed to set_nonblocking , this function does not do anything with the stream, and it doesn't even have to be open.
set_read_callback , set_write_callback , set_read_oob_callback , set_write_oob_callback , set_close_callback , query_callbacks
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()
array(function(mixed:int)) query_callbacks()
These functions return the currently installed callbacks for the respective events.
query_callbacks returns the callbacks in the same order as set_callbacks and set_nonblocking expect them.
set_nonblocking() , set_read_callback , set_write_callback , set_read_oob_callback , set_write_oob_callback , set_close_callback , set_callbacks
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_callbacks , 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".
Consider using one of ISO-IR-196 ("\e%G" - switch to UTF-8 with return) or ISO-IR-190 ("\e%/G" - switch to UTF-8 level 1 no return) or ISO-IR-191 ("\e%/H" - switch to UTF-8 level 2 no return) or ISO-IR-192 ("\e%/I" - switch to UTF-8 level 3 no return) or ISO-IR-193 ("\e%/J" - switch to UTF-16 level 1 no return) or ISO-IR-194 ("\e%/K" - switch to UTF-16 level 2 no return) or ISO-IR-195 ("\e%/L" - switch to UTF-16 level 3 no return) or ISO-IR-162 ("\e%/@" - switch to UCS-2 level 1) or ISO-IR-163 ("\e%/A" - switch to UCS-4 level 1) or ISO-IR-174 ("\e%/C" - switch to UCS-2 level 2) or ISO-IR-175 ("\e%/D" - switch to UCS-4 level 2) or ISO-IR-176 ("\e%/E" - switch to UCS-2 level 3) or ISO-IR-177 ("\e%/F" - switch to UCS-4 level 3) or ISO-IR-178 ("\e%B" - switch to UTF-1) automatically to encode wide strings.
string gets(int(0..1)|void not_all)
Read one line of input with support for input conversion.
Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.
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, int(0..1)|void not_all)
Get n lines.
Number of lines to get, or all remaining if zero.
Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.
File pipe(int|void flags)
Same as Stdio.File()->pipe() .
Returns an Stdio.File object, NOT an Stdio.FILE object.
In future releases of Pike this will most likely change
to returning an Stdio.FILE object. This is already
the case if STDIO_DIRECT_FD
has been defined.
FILE openat(string filename, string mode)
FILE openat(string filename, string mode, int mask)
Same as Stdio.File()->openat() , but returns a Stdio.FILE object.
Stdio.File()->openat()
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.
It's not supported to call this method more than once unless a call to seek is done in advance. Also note that it's not possible to intermingle calls to read , gets or other functions that read data with the line iterator, it will produce unexpected results since the internal buffer in the iterator will not contain sequential file-data in those cases.
_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() , unread()
void unread(string s)
This function puts a string back in the input buffer. The string can then be read with eg read() , gets() or getchar() .
read() , gets() , getchar() , ungets()
void ungets(string s)
This function puts a line back in the input buffer. The line can then be read with eg read() , gets() or getchar() .
The string is autoterminated by an extra line-feed.
read() , gets() , getchar() , unread()
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, this function 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 bind , except that instead of creating a new socket and bind it to a port, it expects the file descriptor fd to be 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)
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 and should typically call accept to establish a connection.
If the optional argument ip is given, bind will try to bind to an interface with that host name or IP number.
1 is returned on success, zero on failure. errno provides further details about the error in the latter case.
accept , set_id
int bind_unix(string path, void|function accept_callback)
Opens a Unix domain socket at the given path in the file system. 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 and should typically call accept to establish a connection.
1 is returned on success, zero on failure. errno provides further details about the error in the latter case.
This function is only available on systems that support Unix domain sockets.
path had a quite restrictive length limit (~100 characters) prior to Pike 7.8.334.
accept , set_id
void close()
Closes the socket.
void Stdio.Port(int|string port, void|function accept_callback, void|string ip)
void Stdio.Port("stdin", void|function accept_callback)
When called with an int or any string except "stdin"
as
first argument, this function does the same as bind() would do
with the same arguments.
When called with "stdin"
as argument, a socket is created
out of the file descriptor 0. This is only useful if that actually
IS a socket to begin with.
bind , listen_fd
Stdio.File accept()
Get the first connection request waiting for this port and return it as a connected socket.
If no connection request is waiting and the port is in nonblocking mode (i.e. an accept callback is installed) then zero is returned. Otherwise this function waits until a connection has arrived.
In Pike 7.8 and later the returned object is created via fd_factory() .
In Pike 7.7 and later the resulting file object will be assigned to the same backend as the port object.
string query_address()
Get the address and port of the local socket end-point.
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 there is some error querying or formatting the address,
0
(zero) is returned and errno() will return the
error code.
An error is thrown if the socket isn't bound.
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
Fd fd_factory()
Factory creating empty Fd objects.
This function is called by accept() when it needs to create a new file.
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.
UDP bind(int|string port)
UDP bind(int|string port, string address)
Binds a port for receiving or transmitting UDP.
Throws error when unable to bind port.
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) enable_multicast(string reply_address)
Set the local device for a multicast socket. See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF.
int set_multicast_ttl(int ttl)
Set the time-to-live value of outgoing multicast packets for this socket. It is very important for multicast packets to set the smallest TTL possible. The default is 1 which means that multicast packets don't leacl the local network unless the user program explicitly request it. See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL.
int add_membership(string group, void|string address)
Join a multicast group. group contains the address of the multicast group the application wants to join or leave. It must be a valid multicast address. address is the address of the local interface with wich the system should join to the multicast group. If not provided the system will select an appropriate interface. See also the Unix man page for setsocketopt IPPROTO_IP ADD_MEMBERSHIP.
drop_membership
int drop_membership(string group, void|string address)
Leave a multicast group.
add_membership
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() , MSG_OOB , MSG_PEEK
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 recipient 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.
UDP set_type(int sock_type)
UDP set_type(int sock_type, int family)
Sets socket type and protocol family.
array(int) get_type()
Returns socket type and protocol family.
constant Stdio.UDP.MSG_OOB
Document this constant.
constant Stdio.UDP.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 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 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 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 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 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) Stdio.Terminfo.Termcap.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) Stdio.Terminfo.Terminfo.aliases
string tputs(string s)
Document this function
void Stdio.Terminfo.Terminfo(string filename)
CLASS Stdio.Terminfo.TermcapDB |
Termcap database
CLASS Stdio.Terminfo.TerminfoDB |
Terminfo database for a single directory.
CLASS Stdio.Terminfo.MetaTerminfoDB |
TerminfoDB that merges several directorys.
void Stdio.Terminfo.MetaTerminfoDB(array(TerminfoDB|string)|void dbs)
Create a new Meta TerminfoDB .
Array with elements in priority order. Elements may be either
|
If the resulting set of TerminfoDB 's is empty, the object will be destructed.
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()
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) get_all_active_fd()
Returns the id of all the active file descriptors.
constant Stdio.PROP_SEND_FD
The Stdio.File object might support the Stdio.File()->send_fd() operation.
Stdio.File()->pipe() , Stdio.File()->send_fd() , Stdio.File()->receive_fd()
constant Stdio.PROP_REVERSE
Request reversed operation.
Used as argument to Stdio.File()->pipe() , when PROP_BIDIRECTIONAL hasn't been specified, to request the direction of the resulting pipe to reversed.
Stdio.File()->pipe()
constant Stdio.PROP_BIDIRECTIONAL
The file is bi-directional.
Stdio.File()->pipe()
constant Stdio.PROP_BUFFERED
The file is buffered (usually 4KB).
Stdio.File()->pipe()
constant Stdio.PROP_SHUTDOWN
The file supports shutting down transmission in either direction.
Stdio.File()->close() , Stdio.File()->pipe()
constant Stdio.PROP_NONBLOCK
The file supports nonblocking I/O.
Stdio.File()->pipe()
constant Stdio.PROP_IPC
The file may be used for inter process communication.
Stdio.File()->pipe()
constant Stdio.__HAVE_SEND_FD__
Support for sending of file descriptors over Stdio.File()->pipe() objects with PROP_SEND_FD capability is supported.
Stdio.File()->send_fd() , Stdio.File()->receive_fd() , Stdio.File()->read() , Stdio.File()->write() , Stdio.File()->pipe()
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 _sprintf(int type, void|mapping flags)
mapping(string:mapping) gethostip()
Returns the IP addresses of the host.
Returns a mapping that maps interface name to a mapping with more information about that interface. That information mapping looks as follows.
|
constant Stdio.XATTR_CREATE
Used by setxattr function and method to signify a pure create, which will fail if the attribute already exists.
constant Stdio.XATTR_REPLACE
Used by setxattr function and method to signify a replace, which will fail the the attribute does not already exists.
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
constant Stdio.DATA_CHUNK_SIZE
Size used in various places to divide incoming or outgoing data into chunks.
constant Stdio.TCSANOW
Argument to Stdio.File()->tcsetattr() .
Change immediately.
constant Stdio.TCSADRAIN
Argument to Stdio.File()->tcsetattr() .
Change after all output has been written.
constant Stdio.TCSAFLUSH
Argument to Stdio.File()->tcsetattr() .
Change after all output has been written, and empty the input buffers.
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 read_file(string filename)
string read_file(string filename, int start, int len)
Read len lines from a regular 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.
Throws an error on any I/O error except when the file doesn't exist.
Returns 0
(zero) if the file doesn't exist or if
start is beyond the end of it.
Returns a string with the requested data otherwise.
read_bytes() , write_file()
string read_bytes(string filename, int start, int len)
string read_bytes(string filename, int start)
string read_bytes(string filename)
Read len number of bytes from a regular 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 on any I/O error except when the file doesn't exist.
Returns 0
(zero) if the file doesn't exist or if
start is beyond the end of it.
Returns a string with the requested data otherwise.
read_file , write_file() , append_file()
int 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, i.e. sizeof(str)
.
append_file() , read_bytes() , Stdio.File()->open()
int 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, i.e. sizeof(str)
.
write_file() , read_bytes() , Stdio.File()->open()
int 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, -3 that it is a symlink and -4 that it is a device.
file_stat() , write_file() , read_bytes()
string append_path(string absolute, string ... relative)
string append_path_unix(string absolute, string ... relative)
string append_path_nt(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).
append_path_nt() fixes drive letter issues in relative
by removing the colon separator ":"
if it exists (k:/fnord appends
as k/fnord)
append_path_nt() also makes sure that UNC path(s) in relative is appended
correctly by removing any "\\"
or "//"
from the beginning.
append_path() is equivalent to append_path_unix() on UNIX-like operating systems, and equivalent to append_path_nt() on NT-like operating systems.
combine_path()
string simplify_path(string path)
Returns a canonic representation of path (without /./, /../, // and similar path segments).
void 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 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 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 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 exist(string path)
Check if a path exists.
Returns true if the given path exists (is a directory or file), otherwise false.
May fail with eg errno() EFBIG if the file exists, but the filesystem doesn't support the file size.
is_dir() , is_file() , is_link() , file_stat()
int convert_modestring2int(string mode_string)
Convert the mode_string string as returned by Stdio.Stat object to int suitable for chmod
The string as return from Stdio.Stat()->mode_string
An int matching the permission of the mode_string string suitable for chmod
int 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. This function can also copy directories recursively.
0 on error, 1 on success
This function keeps file and directory mode bits, unlike in Pike 7.6 and earlier.
int 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 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 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 recursive_rm(string path)
Remove a file or a directory tree.
Returns 0 on failure, nonzero otherwise.
rm
int recursive_mv(string from, string to)
Copy a file or a directory tree by copying and then removing. Mode bits are preserved in the copy. It's not the fastest but works on every OS and works well across different file systems.
Returns 0 on failure, nonzero otherwise.
recursive_rm cp
object sendfile(array(string) headers, File from, int offset, int len, array(string) trailers, File to)
object 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 both before and 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.
In Pike 7.4.496, Pike 7.6.120 and Pike 7.7 and later the backend associated with to will be used rather than the default backend. Note that you usually will want from to have the same backend as to .
FIXME: Support for timeouts?
Stdio.File->set_nonblocking()
void 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.UDP |
UDP (User Datagram Protocol) handling.
int(0..1) close()
Closes an open UDP port.
This method was introduced in Pike 7.5.
UDP bind(int|string port)
UDP bind(int|string port, string address)
Binds a port for receiving or transmitting UDP.
Throws error when unable to bind port.
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) enable_multicast(string reply_address)
Set the local device for a multicast socket. See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF.
int set_multicast_ttl(int ttl)
Set the time-to-live value of outgoing multicast packets for this socket. It is very important for multicast packets to set the smallest TTL possible. The default is 1 which means that multicast packets don't leacl the local network unless the user program explicitly request it. See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL.
int add_membership(string group, void|string address)
Join a multicast group. group contains the address of the multicast group the application wants to join or leave. It must be a valid multicast address. address is the address of the local interface with wich the system should join to the multicast group. If not provided the system will select an appropriate interface. See also the Unix man page for setsocketopt IPPROTO_IP ADD_MEMBERSHIP.
drop_membership
int drop_membership(string group, void|string address)
Leave a multicast group.
add_membership
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() , MSG_OOB , MSG_PEEK
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 recipient 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.
UDP set_type(int sock_type)
UDP set_type(int sock_type, int family)
Sets socket type and protocol family.
array(int) get_type()
Returns socket type and protocol family.
constant Stdio.UDP.MSG_OOB
Document this constant.
constant Stdio.UDP.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()
CLASS Stdio.Fd_ref |
Proxy class that contains stub functions that call the corresponding functions in Fd .
Used by File .
Fd Stdio.Fd_ref._fd
Object to which called functions are relayed.
CLASS Stdio.Fd |
Low level I/O operations. Use File instead.
Fd fd_factory()
Factory creating Stdio.Fd objects.
This function is called by openat() , pipe() , dup() and other functions creating new file objects.
The default implementation calls object_program(this_object())()
to create the new object, and returns the Fd inherit in it.
Note that this function must return the Fd inherit in the object.
Stdio.Port()->fd_factory() , openat() , pipe()
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
void receive_fd(Stdio.Fd fd)
Remote file descriptor reception handler.
File descriptor received from the remote end of a pipe() . This object has been created by fd_factory() .
This function is called from read() when a remote file descriptor has been received over a PROP_SEND_FD capable pipe() .
The default implementation is just a prototype.
Overload this function to enable reception of remote file descriptors.
The capability of sending and receiving remote file descriptors is only available on some operating systems. This capability is indicated by the precence of __HAVE_SEND_FD__ .
send_fd() , read() , fd_factory() , __HAVE_SEND_FD__
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() does not try its best to read as many bytes as you have asked for, but merely returns as much as the system read function returns. This is 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() only blocks if there's no data at all available.
If something goes wrong and not_all is set, zero is 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() fails and returns zero, however.
If everything went fine, a call to errno() directly afterwards returns zero. That includes an end due to end-of-file or remote close.
If no arguments are given, read() reads to the end of the file or stream.
If any file descriptors have been sent by the other side of the stream, receive_fd() will be called once for every sent file descriptor.
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() , receive_fd() , send_fd()
int(-1..1) peek()
int(-1..1) peek(int|float timeout)
int(-1..1) peek(int|float timeout, int not_eof)
Check if there is data available to read, or wait some time for available data to read.
More specifically, a later call to read() will return immediately, either due to data being present, or due to some error (eg if a socket has been closed).
Timeout in seconds.
Flag for specifying handling of end of file. The following values are currently defined:
|
|
errno() , read()
The function may be interrupted prematurely of the timeout (due to signals); check the timing manually if this is imporant.
The not_eof parameter was added in Pike 7.7.
This function was not available on NT in Pike 7.6 and earlier.
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() only returns as many bytes of out-of-band data as are currently available.
If something goes wrong and not_all is set, zero is 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() fails and returns zero, however.
If everything went fine, a call to errno() directly afterwards returns zero. That includes an end due to remote close.
If no arguments are given, read_oob() reads to the end of the stream.
Out-of-band data was not supported in Pike 0.5 and earlier, and not in 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 is 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() returns 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() fails and returns -1.
If everything went fine, a call to errno() directly afterwards returns zero.
If data is an array of strings, they are written in sequence.
If more than one argument is given, sprintf() is 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.
If there are any file descriptors that have been queued for sending (with send_fd() ), they will be sent.
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() , send_fd()
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() fails and returns -1.
If everything went fine, a call to errno() directly afterwards returns zero.
If more than one argument is given, sprintf() is used to format them.
Out-of-band data was not supported in Pike 0.5 and earlier, and not in 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 is received. Most streams only allow for a single byte of out-of-band data at a time. Some streams sends the rest of the data as ordinary data.
read_oob() , write()
void send_fd(Stdio.Fd fd)
Queues an open file descriptor for sending to the other end of a stream.
The actual sending is performed at the next successful call to write() , this is due to limitations in the system calls. This means that it isn't possible to send a file descriptor without also sending some in-band data.
This operation is only supported on pipe() 's created with PROP_SEND_FD .
This function is not available on all operating systems, check for __HAVE_SEND_FD__ .
The queue is emptied on successful write() and when the write direction is close() 'd.
receive_fd() , write() , pipe() , read() , __HAVE_SEND_FD__
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 is closed. Otherwise only the directions specified is 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 is 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 fails 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 defaults to
00666
, but note that on UNIX systems it's masked with the
process umask before use.
Returns nonzero on success and 0
(zero) on failure. If
there is a failure then errno returns the error code.
close()
Stdio.File openat(string filename, string mode)
Stdio.File openat(string filename, string mode, int access)
Open a file relative to an opened directory.
Returns a new file object on success, and 0
(zero) on failure.
Not available on all architectures, or in Pike 7.6 and earlier.
open() , statat() , unlinkat()
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 is calculated as
pos = unit *mult + add
.
If pos is negative then it is relative to the end of the file, otherwise it's 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) is 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() , statat()
Stat statat(string path, void|int(0..1) symlink)
Get status for a file relative an open directory.
This function returns the same information as the function
file_stat() , but relative to the file it is called in. If file is not
an open file, 0
(zero) is returned. Zero is also returned
if file is a pipe or socket.
See file_stat() for a description of the return value.
Not available on all architectures, or in Pike 7.6 and earlier.
file_stat() , stat() , openat() , unlinkat()
int unlinkat(string f)
Remove a file or directory relative to an open file.
Returns 0
(zero) on failure, 1
otherwise.
rm() , openat() , statat()
array(string) listxattr()
Return an array of all extended attributes set on the file
string getxattr(string attr)
Return the value of a specified attribute, or 0 if it does not exist
void removexattr(string attr)
Remove the specified extended attribute.
void setxattr(string attr, string value, int flags)
Set the attribute attr to the value value .
The flags parameter can be used to refine the semantics of the operation.
Stdio.XATTR_CREATE specifies a pure create, which fails if the named attribute exists already.
Stdio.XATTR_REPLACE specifies a pure replace operation, which fails if the named attribute does not already exist.
By default (no flags), the extended attribute will be created if need be, or will simply replace the value if the attribute exists.
1 if successful, 0 otherwise, setting errno.
int errno()
Return the errno for the latest failed file operation.
int mode()
Returns the open mode and capabilities for the file.
Returns an `|() of the following flags:
|
In some versions of Pike 7.7 and 7.8 the PROP_ flags were filtered from the result.
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.
If the file is a socket that has been closed from the remote side, this function might still return true.
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.
Returns 1
on success and 0
(zero) on failure.
In Pike 7.7 and later to need not be open, in which case a new fd is allocated.
Note also that to is also assigned to the same backend (if any) as this object.
assign() , dup()
Stdio.Fd dup()
Duplicate the file.
dup2()
int(0..1) open_socket(int|void port, string|void addr, int|string|void family_hint)
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.
Filename to create.
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.
path had a quite restrictive length limit (~100 characters) prior to Pike 7.8.334.
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 is returned. Otherwise, if local
is 1
, the local end-point is 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). IPv6 addresses
may use the contracted syntax.
If this file is not a socket, is not connected, or some other
error occurs, 0
(zero) is returned and errno() will
return the error code.
An error is thrown if the socket (or file) isn't open.
connect()
Stdio.File `<<(string data)
Stdio.File `<<(mixed data)
Write some data to a file.
If data is not a string, it is 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, int 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()
void 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.
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
inherit Fd : Fd
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|string|void family_hint)
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. The port can also be specified as a string, giving the name of the service associated with the port.
You may specify an address to bind to if your machine has many IP numbers.
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. If you do not want to specify a bind address, you can provide the address as a hint here instead, to allow the automatic selection to work anyway.
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() , send_fd() , receive_fd() , PROP_IPC , PROP_NONBLOCK , PROP_SEND_FD , PROP_SHUTDOWN , PROP_BUFFERED , PROP_REVERSE , PROP_BIDIRECTIONAL
File openat(string filename, string mode)
File openat(string filename, string mode, int mask)
Open a file relative to an open directory.
File.statat() , File.unlinkat()
int(0..1) send_fd(File|Fd file)
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.
This callback is also called after the remote end of a socket connection has closed the write direction. An attempt to write data to it in that case will generate a System.EPIPE errno. If the remote end has closed both directions simultaneously (the usual case), Pike will first attempt to call close_cb , then this callback (unless close_cb has closed the stream).
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.
If the OS doesn't separate the write events for normal and out-of-band data, Pike will try to call write_oob_cb first. If it doesn't write anything, then write_cb will be tried. This also means that write_oob_cb might get called when the remote end of a connection has closed the write direction.
When an error or an end-of-stream in the read direction occurs, close_cb will be called. errno will return the error, or zero in the case of an end-of-stream.
The name of this callback is rather unfortunate since it really has nothing to do with a close: The stream is still open when close_cb is called (you might not be able to read and/or write to it, but you can still use things like query_address , and the underlying file descriptor is still allocated). Also, this callback will not be called for a local close, neither by a call to close or by destructing this object.
Also, close_cb will not be called if a remote close only occurs in the write direction; that is handled by write_cb (or possibly write_oob_cb ).
Events to read_cb and close_cb will be automatically deregistered if an end-of-stream occurs, and all events in the case of an error. I.e. there won't be any more calls to the callbacks unless they are reinstalled. This doesn't affect the callback settings - query_read_callback et al will still return the installed callbacks.
If the stream is a socket performing a nonblocking connect (see open_socket and connect ), a connection failure will call close_cb , and a successful connect will call either read_cb or write_cb as above.
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_callbacks and 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_callbacks , set_nonblocking() , set_id() , set_backend , query_read_callback , query_write_callback , query_read_oob_callback , query_write_oob_callback , query_close_callback
void set_callbacks(void|function(mixed:int) read_cb, void|function(mixed:int) write_cb, void|function(mixed:int) close_cb, void|function(mixed:int) read_oob_cb, void|function(mixed:int) write_oob_cb)
Installs all the specified callbacks at once. Use UNDEFINED to keep the current setting for a callback.
Like set_nonblocking , the callbacks are installed atomically. As opposed to set_nonblocking , this function does not do anything with the stream, and it doesn't even have to be open.
set_read_callback , set_write_callback , set_read_oob_callback , set_write_oob_callback , set_close_callback , query_callbacks
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()
array(function(mixed:int)) query_callbacks()
These functions return the currently installed callbacks for the respective events.
query_callbacks returns the callbacks in the same order as set_callbacks and set_nonblocking expect them.
set_nonblocking() , set_read_callback , set_write_callback , set_read_oob_callback , set_write_oob_callback , set_close_callback , set_callbacks
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_callbacks , 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.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, this function 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 bind , except that instead of creating a new socket and bind it to a port, it expects the file descriptor fd to be 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)
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 and should typically call accept to establish a connection.
If the optional argument ip is given, bind will try to bind to an interface with that host name or IP number.
1 is returned on success, zero on failure. errno provides further details about the error in the latter case.
accept , set_id
int bind_unix(string path, void|function accept_callback)
Opens a Unix domain socket at the given path in the file system. 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 and should typically call accept to establish a connection.
1 is returned on success, zero on failure. errno provides further details about the error in the latter case.
This function is only available on systems that support Unix domain sockets.
path had a quite restrictive length limit (~100 characters) prior to Pike 7.8.334.
accept , set_id
void close()
Closes the socket.
void Stdio.Port(int|string port, void|function accept_callback, void|string ip)
void Stdio.Port("stdin", void|function accept_callback)
When called with an int or any string except "stdin"
as
first argument, this function does the same as bind() would do
with the same arguments.
When called with "stdin"
as argument, a socket is created
out of the file descriptor 0. This is only useful if that actually
IS a socket to begin with.
bind , listen_fd
Stdio.File accept()
Get the first connection request waiting for this port and return it as a connected socket.
If no connection request is waiting and the port is in nonblocking mode (i.e. an accept callback is installed) then zero is returned. Otherwise this function waits until a connection has arrived.
In Pike 7.8 and later the returned object is created via fd_factory() .
In Pike 7.7 and later the resulting file object will be assigned to the same backend as the port object.
string query_address()
Get the address and port of the local socket end-point.
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 there is some error querying or formatting the address,
0
(zero) is returned and errno() will return the
error code.
An error is thrown if the socket isn't bound.
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
Fd fd_factory()
Factory creating empty Fd objects.
This function is called by accept() when it needs to create a new file.
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.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 in addition to some features of a Stdio.FILE object.
constant Stdio.FakeFile.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()
Stdio.Stat stat()
Returns size and the creation time of the string.
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()
string gets()
Stdio.FILE()->gets()
int getchar()
Stdio.FILE()->getchar()
void unread(string s)
Stdio.FILE()->unread()
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()
void set_blocking()
Stdio.File()->set_blocking
void set_blocking_keep_callbacks()
Stdio.File()->set_blocking_keep_callbacks
void set_nonblocking(function rcb, function wcb, function ccb, function rocb, function wocb)
Stdio.File()->set_blocking
void set_nonblocking_keep_callbacks()
Stdio.File()->set_blocking_keep_callbacks
void set_close_callback(function cb)
Stdio.File()->set_close_callback
void set_read_callback(function cb)
Stdio.File()->set_read_callback
void set_read_oob_callback(function cb)
Stdio.File()->set_read_oob_callback
void set_write_callback(function cb)
Stdio.File()->set_write_callback
void set_write_oob_callback(function cb)
Stdio.File()->set_write_oob_callback
function query_close_callback()
Stdio.File()->query_close_callback
function query_read_callback()
Stdio.File()->query_read_callback
function query_read_oob_callback()
Stdio.File()->query_read_oob_callback
function query_write_callback()
Stdio.File()->query_write_callback
function query_write_oob_callback()
Stdio.File()->query_write_oob_callback
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.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()
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)
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
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".
Consider using one of ISO-IR-196 ("\e%G" - switch to UTF-8 with return) or ISO-IR-190 ("\e%/G" - switch to UTF-8 level 1 no return) or ISO-IR-191 ("\e%/H" - switch to UTF-8 level 2 no return) or ISO-IR-192 ("\e%/I" - switch to UTF-8 level 3 no return) or ISO-IR-193 ("\e%/J" - switch to UTF-16 level 1 no return) or ISO-IR-194 ("\e%/K" - switch to UTF-16 level 2 no return) or ISO-IR-195 ("\e%/L" - switch to UTF-16 level 3 no return) or ISO-IR-162 ("\e%/@" - switch to UCS-2 level 1) or ISO-IR-163 ("\e%/A" - switch to UCS-4 level 1) or ISO-IR-174 ("\e%/C" - switch to UCS-2 level 2) or ISO-IR-175 ("\e%/D" - switch to UCS-4 level 2) or ISO-IR-176 ("\e%/E" - switch to UCS-2 level 3) or ISO-IR-177 ("\e%/F" - switch to UCS-4 level 3) or ISO-IR-178 ("\e%B" - switch to UTF-1) automatically to encode wide strings.
string gets(int(0..1)|void not_all)
Read one line of input with support for input conversion.
Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.
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, int(0..1)|void not_all)
Get n lines.
Number of lines to get, or all remaining if zero.
Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.
File pipe(int|void flags)
Same as Stdio.File()->pipe() .
Returns an Stdio.File object, NOT an Stdio.FILE object.
In future releases of Pike this will most likely change
to returning an Stdio.FILE object. This is already
the case if STDIO_DIRECT_FD
has been defined.
FILE openat(string filename, string mode)
FILE openat(string filename, string mode, int mask)
Same as Stdio.File()->openat() , but returns a Stdio.FILE object.
Stdio.File()->openat()
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.
It's not supported to call this method more than once unless a call to seek is done in advance. Also note that it's not possible to intermingle calls to read , gets or other functions that read data with the line iterator, it will produce unexpected results since the internal buffer in the iterator will not contain sequential file-data in those cases.
_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() , unread()
void unread(string s)
This function puts a string back in the input buffer. The string can then be read with eg read() , gets() or getchar() .
read() , gets() , getchar() , ungets()
void ungets(string s)
This function puts a line back in the input buffer. The line can then be read with eg read() , gets() or getchar() .
The string is autoterminated by an extra line-feed.
read() , gets() , getchar() , unread()
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.
Module Stdio.Terminfo |
Termcap 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 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 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 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 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) Stdio.Terminfo.Termcap.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) Stdio.Terminfo.Terminfo.aliases
string tputs(string s)
Document this function
void Stdio.Terminfo.Terminfo(string filename)
CLASS Stdio.Terminfo.TermcapDB |
Termcap database
CLASS Stdio.Terminfo.TerminfoDB |
Terminfo database for a single directory.
CLASS Stdio.Terminfo.MetaTerminfoDB |
TerminfoDB that merges several directorys.
void Stdio.Terminfo.MetaTerminfoDB(array(TerminfoDB|string)|void dbs)
Create a new Meta TerminfoDB .
Array with elements in priority order. Elements may be either
|
If the resulting set of TerminfoDB 's is empty, the object will be destructed.