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
Stdio.File res = Stdio.File() << data
Stdio.File res = Stdio.File() << 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()
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()
int async_connect(string host, int|string port, function(int, mixed ... :void) callback, mixed ... args)
Open a TCP/IP connection asynchronously.
This function is similar to connect(), but works asynchronously.
hostHostname or IP to connect to.
portPort number or service name to connect to.
callbackFunction to be called on completion.
The first argument will be 1 if a connection was
successfully established, and 0 (zero) on failure.
The rest of the arguments to callback are passed
verbatim from args.
argsExtra 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()
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
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()
bool connect(string dest_addr, int dest_port)
bool 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.
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()
bool connect_unix(string filename)
Open a UNIX domain socket connection to the specified destination.
filenameFilename 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 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
Stdio.File Stdio.File()
Stdio.File Stdio.File(string filename)
Stdio.File Stdio.File(string filename, string mode)
Stdio.File Stdio.File(string filename, string mode, int mask)
Stdio.File Stdio.File(string descriptorname)
Stdio.File Stdio.File(int fd)
Stdio.File 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,
Stdio.File Stdio.File(string filename)
Stdio.File Stdio.File(string filename, string mode)
Stdio.File Stdio.File(string filename, string mode, int access)
Stdio.File Stdio.File(int fd)
Stdio.File Stdio.File(int fd, string mode)
See open().
open()
File dup()
This function returns a clone of Stdio.File with all variables copied from this file.
All variables, even id, are copied.
assign()
Stdio.Fd dup()
Duplicate the file.
dup2()
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()
int errno()
Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.
int errno()
Return the errno for the latest failed file operation.
string getxattr(string attr)
Return the value of a specified attribute, or 0 if it does not exist
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.
optional inherit Fd : Fd
optional inherit Fd_ref : Fd_ref
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.
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.
array(string) listxattr()
Return an array of all extended attributes set on the file
Stdio.FileLockKey lock()
Stdio.FileLockKey lock(bool is_recursive)
Makes an exclusive file lock on this file.
trylock()
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 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.
notificationWhat to notify the callback of. See the Stdio.DN_* constants for more information about possible notifications.
callbackFunction 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.
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:
| Open file for reading. |
| Open file for writing. |
| Open file for append (use with |
| Truncate file at open (use with |
| Create file if it doesn't exist (use with |
| Fail if file already exists (use with |
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 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()
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().
portIf 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.
addressYou may specify an address to bind to if your machine has many IP numbers.
family_hintA 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()
bool open_socket(int|void port, string|void addr, int|string|void family_hint)
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()
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. The parameter
mode should contain one or more of the following letters:
| Open terminal for reading. |
| Open terminal for writing. |
mode should always contain at least one of the letters
"r" or "w".
grantpt()
int openpt(string mode)
Open the master end of a pseudo-terminal pair.
This function returns 1 for success, 0 otherwise.
grantpt()
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).
timeoutTimeout in seconds.
not_eofFlag for specifying handling of end of file. The following values are currently defined:
| Traditional (and default) behaviour. Return |
| Regard EOF as an error. Return |
| There is data available to |
| There is no data available (ie timeout). |
| Error condition. The error code returned by |
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.
Stdio.File pipe()
Stdio.File pipe(int flags)
File pipe(void|int required_properties)
This function creates a pipe between the object it was called in and an object that is returned.
required_propertiesBinary or (predef::`|()) of required PROP_ properties.
| The resulting pipe may be used for inter process communication. |
| The resulting pipe supports nonblocking I/O. |
| The resulting pipe supports shutting down transmission in either
direction (see |
| The resulting pipe is buffered (usually 4KB). |
| The resulting pipe is bi-directional. |
| The resulting pipe might support sending of file descriptors
(see |
| The resulting pipe supports communication "backwards" (but
not necessarily "forwards", see |
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
void proxy(Stdio.File from)
Starts a thread that asynchronously copies data from from
to this file.
Stdio.sendfile()
string query_address()
string query_address(bool local)
Get address and port of a socket end-point.
localIf 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()
Pike.Backend query_backend()
Return the backend used for the callbacks.
set_backend
function(mixed, string:int) query_read_callback()
function(mixed:int) query_write_callback()
function(mixed, string:int) query_read_oob_callback()
function(mixed:int) query_write_oob_callback()
function(mixed:int) query_close_callback()
array(function(mixed, void|string: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
int query_fd()
Returns the file descriptor number associated with this object.
mixed query_id()
This function returns the id that has been set with set_id().
set_id()
string read()
string read(int len)
string read(int len, bool 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()
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 read_oob()
string read_oob(int len)
string read_oob(int len, bool 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()
void receive_fd(Stdio.Fd fd)
Remote file descriptor reception handler.
fdFile 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__
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 removexattr(string attr)
Remove the specified extended attribute.
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()
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__
bool send_fd(File|Fd file)
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, set_fs_event_callback
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_blocking()
Sets this file to blocking operation.
This is the inverse operation of set_nonblocking().
set_nonblocking()
void set_nonblocking_keep_callbacks()
void set_blocking_keep_callbacks()
Toggle between blocking and nonblocking, without changing the callbacks.
set_nonblocking(), set_blocking()
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()
void set_callbacks(void|function(mixed, string:int) read_cb, void|function(mixed:int) write_cb, void|function(mixed:int) close_cb, void|function(mixed, string: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
void set_read_callback(function(mixed, string:int) read_cb)
void set_write_callback(function(mixed:int) write_cb)
void set_read_oob_callback(function(mixed, string:int) read_oob_cb)
void set_write_oob_callback(function(mixed:int) write_oob_cb)
void set_close_callback(function(mixed:int) close_cb)
void set_fs_event_callback(function(mixed, int:int) fs_event_cb, int event_mask)
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.
event_maskAn event mask specifing bitwise OR of one or more event types to
monitor, selected from Stdio.NOTE_WRITE and friends.
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.
fs_event callbacks only trigger on systems that support these events. Currently, this includes systems that use kqueue, such as Mac OS X, and various flavours of BSD.
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_close_on_exec(bool 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()
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()
bool set_keepalive(bool on_off)
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_nonblocking(function(mixed, string:int) read_callback, function(mixed:int) write_callback, function(mixed:int) close_callback)
void set_nonblocking(function(mixed, string:int) read_callback, function(mixed:int) write_callback, function(mixed:int) close_callback, function(mixed, string: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 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.
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|bool 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()
bool sync()
Flush buffers to disk.
Returns 0 (zero) and sets errno on failure.
Returns 1 on success.
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()
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
| In baud rate. |
| Out baud rate. |
| Character size in bits. |
| Terminal rows. |
| Terminal columns. |
| The value of a named flag. The flag name is the string describing the termios flags (IGNBRK, BRKINT, IGNPAR, PARMRK, INPCK, ISTRIP, INLCR, IGNCR, ICRNL, IUCLC, IXON, IXANY, IXOFF, IMAXBEL, OPOST, OLCUC, ONLCR, OCRNL, ONOCR, ONLRET, OFILL, OFDEL, OXTABS, ONOEOT, CSTOPB, CREAD, PARENB, PARODD, HUPCL, CLOCAL, CRTSCTS, ISIG, ICANON, XCASE, ECHO, ECHOE, ECHOK, ECHONL, ECHOCTL, ECHOPRT, ECHOKE, FLUSHO, NOFLSH, TOSTOP, PENDIN). See the manpage for termios or other documentation for more information. All flags are not available on all platforms. |
| Sets the value of a control character (VINTR, VQUIT, VERASE, VKILL, VEOF, VTIME, VMIN, VSWTC, VSTART, VSTOP, VSUSP, VEOL, VREPRINT, VDISCARD, VWERASE, VLNEXT, VEOL2). All control characters are not available on all platforms. |
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:
| The change occurs immediately (default). |
| The change occurs after all output has been written. |
| The change occurs after all output has been written, and empties input buffers. |
// 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.
int tell()
Returns the current offset in the file.
seek()
bool truncate(int length)
Truncate a file.
Truncates the file to the specified length length.
Returns 1 on success, and 0 (zero) on failure.
open()
Stdio.FileLockKey trylock()
Stdio.FileLockKey trylock(bool is_recursive)
Attempts to place a file lock on this file.
lock()
int unlinkat(string f)
Remove a file or directory relative to an open file.
Returns 0 (zero) on failure, 1 otherwise.
rm(), openat(), statat()
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()
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.
Stdio.FILE a;
foreach( a; index; value ) orprotected object _get_iterator()
Returns an iterator that will loop over the lines in this file.
line_iterator()
local 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.
string gets(bool|void not_all)
Read one line of input with support for input conversion.
not_allSet 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()
inherit File : file
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()
array(string) ngets(void|int(1..) n, bool|void not_all)
Get n lines.
nNumber of lines to get, or all remaining if zero.
not_allSet this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.
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()
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.
int printf(string format, mixed ... data)
This function does approximately the same as:
write(sprintf(format,@data))
write(), sprintf()
string read(int|void bytes, void|bool now)
Read bytes (wide-) characters with buffering and support for
input conversion.
Stdio.File()->read(), set_charset(), unread()
void set_charset(string|void charset)
Sets the input and output charset of this file to the specified
charset. If charset is 0 or not specified the environment
is used to try to detect a suitable charset.
The default charset if this function is not called 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.
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()
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()
int write(array(string)|string what, mixed ... fmt)
Write what with support for output_conversion.
Stdio.File()->write()
Handles listening to socket ports. Whenever you need a bound socket that is open and listens for connections you should use this program.
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
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.
int bind(int|string port, void|function(:void) 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. Omitting this
will bind to all available IPv4 addresses; specifying "::" will
bind to all IPv4 and IPv6 addresses.
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(:void) 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.
Stdio.Port Stdio.Port()
Stdio.Port Stdio.Port(int|string port)
Stdio.Port Stdio.Port(int|string port, function(:void) accept_callback)
Stdio.Port Stdio.Port(int|string port, function(:void) accept_callback, string ip)
Stdio.Port Stdio.Port("stdin")
Stdio.Port Stdio.Port("stdin", function(:void) 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
Stdio.Port Stdio.Port(int|string port, void|function(:void) accept_callback, void|string ip)
Stdio.Port Stdio.Port("stdin", void|function(:void) 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
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.
protected Fd fd_factory()
Factory creating empty Fd objects.
This function is called by accept() when it needs to create
a new file.
inherit _port : _port
int listen_fd(int fd, void|function(:void) 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
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.
Pike.Backend query_backend()
Return the backend used for the accept callback.
set_backend
mixed query_id()
This function returns the id for this port. The id is normally the first argument to accept_callback.
set_id
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
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
UDP (User Datagram Protocol) handling.
constant Stdio.UDP.MSG_OOB
Document this constant.
constant Stdio.UDP.MSG_PEEK
Document this constant.
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
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.
bool close()
Closes an open UDP port.
This method was introduced in Pike 7.5.
bool 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()
int drop_membership(string group, void|string address)
Leave a multicast group.
add_membership
bool 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.
bool 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 errno()
Returns the error code for the last command on this object. Error code is normally cleared when a command is successful.
array(int) get_type()
Returns socket type and protocol family.
inherit files.UDP : UDP
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.
Pike.Backend query_backend()
Return the backend used for the read callback.
set_backend
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.
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
object set_blocking()
Sets this object to be blocking.
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.
UDP set_nonblocking()
UDP set_nonblocking(function(mapping(string:int|string), mixed ... :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), mixed ... :void) read_cb, mixed ... extra_args)
The read_cb function will receive a mapping similar to the mapping
returned by read():
| Received data. |
| Data was sent from this IP. |
| Data was sent from this port. |
The called object.
read()
UDP set_type(int sock_type)
UDP set_type(int sock_type, int family)
Sets socket type and protocol family.
bool wait(int|float timeout)
Check for data and wait max. timeout seconds.
Returns 1 if data are ready, 0 (zero) otherwise.
protected 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
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 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
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.
TerminfoDB that merges several directorys.
Stdio.Terminfo.MetaTerminfoDB Stdio.Terminfo.MetaTerminfoDB(array(TerminfoDB|string)|void dbs)
Create a new Meta TerminfoDB.
dbsArray with elements in priority order. Elements may be either
| An active |
| A directory that may exist and contain a terminfo database. |
If the resulting set of TerminfoDB's is empty,
the object will be destructed.
Termcap terminal description object.
array(string) Stdio.Terminfo.Termcap.aliases
Stdio.Terminfo.Termcap Stdio.Terminfo.Termcap(string cap, TermcapDB|void tcdb, int|void maxrecurse)
inherit TermMachine : TermMachine
string tputs(string s)
Put termcap string
Termcap database
Terminfo terminal description object
array(string) Stdio.Terminfo.Terminfo.aliases
Stdio.Terminfo.Terminfo Stdio.Terminfo.Terminfo(string filename)
inherit TermMachine : TermMachine
string tputs(string s)
Document this function
Terminfo database for a single directory.
void add_to_kill_ring(string s)
Document this function
Stdio.Readline 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.
infdDefaults to Stdio.stdin.
intermDefaults to Stdio.Terminfo.getTerm().
outfdDefaults to infd, unless infd is 0, in which case
outfd defaults to Stdio.stdout.
outtermDefaults to interm.
void delete(int p1, int p2)
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.
string edit(string data, string|void local_prompt, array(string)|void attrs)
Document this function
void enable_history(array(string)|History|int hist)
Document this function
void eof()
Document this function
History get_history()
Document this function
InputController get_input_controller()
get current input control object
Terminal input controller object
OutputController get_output_controller()
get current output control object
Terminal output controller object
string get_prompt()
Return the current prompt string.
int getcursorpos()
Document this function
int getmark()
Document this function
string gettext()
Document this function
void history(int n)
Document this function
void insert(string s, int p)
Document this function
void kill(int p1, int p2)
Document this function
string kill_ring_yank()
Document this function
void list_completions(array(string) c)
Document this function
void message(string msg)
Print a message to the output device
string newline()
Document this function
array(int) pointmark()
Document this function
string read(string|void prompt, array(string)|void attrs)
Document this function
void redisplay(int clear, int|void nobackup)
Document this function
string region(int ... args)
Document this function
void set_blocking()
Document this function
void set_echo(int onoff)
Set text echo on or off.
onoff1 for echo, 0 for no echo.
void set_nonblocking(function(:void) f)
Document this function
string set_prompt(string newp, array(string)|void newattrs)
Set the prompt string.
newpNew prompt string
newattrsTerminal attributes
int setcursorpos(int p)
Document this function
int setmark(int p)
Document this function
void write(string msg, void|int word_wrap)
Document this function
void backward_char()
void backward_delete_char()
void backward_kill_word()
void backward_word()
void beginning_of_line()
void capitalize_word()
void clear_screen()
Stdio.Readline.DefaultEditKeys Stdio.Readline.DefaultEditKeys(object readline)
void delete_char()
void delete_char_or_eof()
void down_history()
void downcase_word()
void end_of_line()
void forward_char()
void forward_word()
void kill_line()
void kill_region()
void kill_ring_save()
void kill_whole_line()
void kill_word()
void newline()
void quoted_insert()
void redisplay()
void self_insert_command(string str)
protected void set_default_bindings()
void set_mark()
void swap_mark_and_point()
void transpose_chars()
void up_history()
void upcase_word()
void yank()
Stdio.Readline.History Stdio.Readline.History(int maxhist, void|array(string) hist)
string encode()
void finishline(string text)
int get_history_num()
string history(int n, string text)
void initline()
void set_max_history(int maxhist)
Ought to have support for charset conversion.
function(:void) bind(string k, function(:void) f)
function(:void) bindstr(string str, function(:void) f)
function(:void) bindtc(string cap, function(:void) f)
Stdio.Readline.InputController Stdio.Readline.InputController(object|void _infd, object|string|void _term)
int disable()
int enable(int ... e)
function(:void) getbinding(string k, string cap)
mapping(string:function(:void)) getbindings()
function(:void) getbindingstr(string str)
function(:void) getbindingtc(string cap)
void grabnextkey(function(:void) g)
int isenabled()
void nullbindings()
Clears the bindings.
string parsekey(string k)
int run_blocking()
void set_close_callback(function(:int) ccb)
function(:void) unbind(string k)
function(:void) unbindstr(string str)
function(:void) unbindtc(string cap)
Ought to have support for charset conversion.
void beep()
void bol()
int check_columns()
Check and return the terminal width.
In Pike 7.4 and earlier this function returned void.
get_number_of_columns
void clear(int|void partial)
Stdio.Readline.OutputController Stdio.Readline.OutputController(.File|void _outfd, .Terminfo.Termcap|string|void _term)
void disable()
void enable()
void erase(string s)
int get_number_of_columns()
Returns the width of the terminal.
Does not check the width of the terminal.
check_columns
void low_erase(int n)
void low_move_backward(int n)
void low_move_downward(int n)
void low_move_forward(int n)
void low_move_upward(int n)
void low_write(string s, void|int word_break)
void move_backward(string s)
void move_forward(string s)
void newline()
void turn_off(string ... atts)
Set the provided attributes to off.
void turn_on(string ... atts)
Set the provided attributes to on.
void write(string s, void|int word_break, void|int hide)
final constantint Stdio.DATA_CHUNK_SIZE
Size used in various places to divide incoming or outgoing data into chunks.
constant Stdio.DN_ACCESS
Used in File.notify() to get a callback when files
within a directory are accessed.
constant Stdio.DN_ATTRIB
Used in File.notify() to get a callback when attributes
of files within a directory are changed.
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_MODIFY
Used in File.notify() to get a callback when files
within a directory are modified.
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.
constant Stdio.DN_RENAME
Used in File.notify() to get a callback when files
within a directory are renamed.
constant int Stdio.NOTE_ATTRIB
constant int Stdio.NOTE_DELETE
constant int Stdio.NOTE_EXTEND
constant int Stdio.NOTE_LINK
constant int Stdio.NOTE_RENAME
constant int Stdio.NOTE_REVOKE
constant int Stdio.NOTE_WRITE
constant int Stdio.PROP_BIDIRECTIONAL
The file is bi-directional.
Stdio.File()->pipe()
constant int Stdio.PROP_BUFFERED
The file is buffered (usually 4KB).
Stdio.File()->pipe()
constant int Stdio.PROP_IPC
The file may be used for inter process communication.
Stdio.File()->pipe()
constant int Stdio.PROP_NONBLOCK
The file supports nonblocking I/O.
Stdio.File()->pipe()
constant int 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 int 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 int Stdio.PROP_SHUTDOWN
The file supports shutting down transmission in either direction.
Stdio.File()->close(), Stdio.File()->pipe()
constant string Stdio.TCSADRAIN
Argument to Stdio.File()->tcsetattr().
Change after all output has been written.
constant string Stdio.TCSAFLUSH
Argument to Stdio.File()->tcsetattr().
Change after all output has been written, and empty the input buffers.
constant string Stdio.TCSANOW
Argument to Stdio.File()->tcsetattr().
Change immediately.
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.__HAVE_OOB__
Exists and has the value 1 if OOB operations are available.
In Pike 7.5 and later OOB operations are always present.
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.
| Nonblocking OOB support is not supported. |
| Nonblocking OOB works a little. |
| Nonblocking OOB almost works. |
| Nonblocking OOB works as intended. |
| Unknown level of nonblocking OOB support. |
This constant only exists when OOB operations are
available, i.e. when __HAVE_OOB__ is 1.
string _sprintf(int type, void|mapping flags)
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()
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()
void async_cp(string from, string to, function(int, mixed ... :void) callback, mixed ... args)
Copy a file asynchronously.
This function is similar to cp(), but works asynchronously.
fromName of file to copy.
toName of file to create or replace with a copy of from.
callbackFunction 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.
argsExtra 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 convert_modestring2int(string mode_string)
Convert the mode_string string as returned by Stdio.Stat object to int suitable for chmod
mode_stringThe 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 DATA_CHUNK_SIZE 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 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 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.
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()
array(int) get_all_active_fd()
Returns the id of all the active file descriptors.
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.
| A list of all IP addresses bound to this interface. |
inherit files : files
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_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_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 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()
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()
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()
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()
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
int recursive_rm(string path)
Remove a file or a directory tree.
Returns 0 on failure, nonzero otherwise.
rm
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, mixed ... :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()
string simplify_path(string path)
Returns a canonic representation of path (without /./, /../, //
and similar path segments).
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.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); }
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()
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()
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()
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
A string wrapper that pretends to be a Stdio.File object
in addition to some features of a Stdio.FILE object.
int(0..) sizeof( Stdio.FakeFile arg )
Sizeof on a FakeFile returns the size of its contents.
(int)Stdio.FakeFile()
(float)Stdio.FakeFile()
(string)Stdio.FakeFile()
(array)Stdio.FakeFile()
(mapping)Stdio.FakeFile()
(multiset)Stdio.FakeFile()
A FakeFile can be casted to a string.
int close(void|string direction)
Stdio.File()->close()
Stdio.FakeFile 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()
int getchar()
Stdio.FILE()->getchar()
string gets()
Stdio.FILE()->gets()
constant int Stdio.FakeFile.is_fake_file
This constant can be used to distinguish a FakeFile object
from a real Stdio.File object.
String.SplitIterator line_iterator(int|void trim)
Stdio.File()->line_iterator()
int(-1..1) peek(int|float|void timeout)
Stdio.File()->peek()
string query_address(void|bool is_local)
Always returns 0.
Stdio.File()->query_address()
function(:void) query_close_callback()
Stdio.File()->query_close_callback
mixed query_id()
Stdio.File()->query_id()
function(:void) query_read_callback()
Stdio.File()->query_read_callback
function(:void) query_read_oob_callback()
Stdio.File()->query_read_oob_callback
function(:void) query_write_callback()
Stdio.File()->query_write_callback
function(:void) query_write_oob_callback()
Stdio.File()->query_write_oob_callback
string read(void|int(0..) len, void|bool not_all)
Stdio.File()->read()
function(:string) read_function(int nbytes)
Stdio.File()->read_function()
int seek(int pos, void|int mult, void|int add)
Stdio.File()->seek()
void set_blocking()
Stdio.File()->set_blocking
void set_blocking_keep_callbacks()
Stdio.File()->set_blocking_keep_callbacks
void set_close_callback(function(:void) cb)
Stdio.File()->set_close_callback
void set_id(mixed _id)
Stdio.File()->set_id()
void set_nonblocking(function(:void) rcb, function(:void) wcb, function(:void) ccb, function(:void) rocb, function(:void) wocb)
Stdio.File()->set_blocking
void set_nonblocking_keep_callbacks()
Stdio.File()->set_blocking_keep_callbacks
void set_read_callback(function(:void) cb)
Stdio.File()->set_read_callback
void set_read_oob_callback(function(:void) cb)
Stdio.File()->set_read_oob_callback
void set_write_callback(function(:void) cb)
Stdio.File()->set_write_callback
void set_write_oob_callback(function(:void) cb)
Stdio.File()->set_write_oob_callback
Stdio.Stat stat()
Returns size and the creation time of the string.
int(1..1) sync()
Always returns 1.
Stdio.File()->sync()
int tell()
Stdio.File()->tell()
bool truncate(int length)
Stdio.File()->truncate()
void unread(string s)
Stdio.FILE()->unread()
int(-1..) write(string|array(string) str, mixed ... extra)
Stdio.File()->write()
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
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:
| Array | |
| File mode, same as mode. |
| If zero or greater, the file is a regular file and this is its size in bytes. If less than zero it gives the type: -2=directory, -3=symlink and -4=device. |
| Time of last access, same as atime. |
| Time of last data modification, same as mtime. |
| Time of last file status change, same as ctime. |
| User ID of the file's owner, same as uid. |
| Group ID of the file's owner, same as gid. |
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.
Stdio.Stat 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).
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