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 by default, and provides no 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
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
variant int connect(string host, int(0..)|string port)
variant int connect(string host, int(0..)|string port, string client, int(0..)|string client_port)
variant string connect(string host, int(0..)|string port, string data)
variant string connect(string host, int(0..)|string port, int(0..0)|string client, int(0..)|string client_port, string data)
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.
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.
If the data argument is included the socket will use
TCP_FAST_OPEN if posible. In this mode the the function will
return the part of the data that has not been sent to the remote
server yet instead of 1 (you will have to use write to send
this data).
Note that TCP_FAST_OPEN requires server support, the connection might fail even though the remote server exists. It might be advicable to retry without TCP_FAST_OPEN (and remember this fact)
This function returns 1 or the remaining data 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
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,
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 errno()
Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.
optional inherit Fd : Fd
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 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_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. Pass -1 to not specify a port (eg to bind only to an address).
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()
File openat(string filename)
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 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()
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 is a pseudo-tty. |
| 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.
For PROP_TTY the returned object is the slave (unless
PROP_REVERSE has been specified).
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, PROP_TTY
array(Stdio.Buffer|int(0..0)) query_buffer_mode()
Get the active input and output buffers that have been
set with set_buffer_mode() (if any).
Returns an array with two elements:
| Array | |
| The current input buffer. |
| The current output buffer. |
set_buffer_mode()
read_callback_t query_read_callback()
write_callback_t 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
mixed query_id()
This function returns the id that has been set with set_id().
set_id()
string(8bit) read(int|void nbytes, bool|void not_all)
Read (optionally buffered) data from a file or a stream.
Proxy function for Fd::read(), that adds support for
the buffering configured by set_buffer_mode()
read_function(), write(), Fd::read()
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.
void send_fd(File|Fd file)
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()
void set_buffer_mode(Stdio.Buffer|int(0..0) in, Stdio.Buffer|int(0..0) out)
Toggle the file to Buffer mode.
In this mode reading and writing will be done via Buffer objects, in the directions you included buffers.
inInput buffer.
outOutput buffer.
Normally you call write to re-trigger the write callback if
you do not output anything in it (which will stop it from
re-occuring again).
This will work with buffered output mode as well, but simply adding more data to the output buffer will work as well.
get_buffer_mode()
void set_callbacks(read_callback_t|void read_cb, write_callback_t|void 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_read_callback(function(mixed, Buffer:int) read_cb)
void set_write_callback(function(mixed:int) write_cb)
void set_write_callback(function(mixed, Buffer: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.
If the file is in buffer mode, the second argument will be a Buffer.
This will always be the same buffer, so data you do not use in one read callback can be simply left in the buffer, when new data arrives it will be appended
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).
If the file is in buffer mode, the second argument will be a Buffer.
You should add data to write to this buffer.
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_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()
void set_nonblocking(read_callback_t read_callback, write_callback_t write_callback, function(mixed:int) close_callback)
void set_nonblocking(read_callback_t read_callback, write_callback_t 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()
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)
FILE openat(string filename, string mode)
FILE openat(string filename, string mode, int mask)
Same as Stdio.File()->openat(), but returns an Stdio.FILE
object.
Stdio.File()->openat()
FILE pipe(void|int flags)
Same as Stdio.File()->pipe(), but returns an Stdio.FILE
object.
Stdio.File()->pipe()
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, void|string reuse_port)
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.
If the OS supports TCP_FASTOPEN it is enabled automatically.
If the OS supports SO_REUSEPORT it is enabled if the fourth argument is true.
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
int query_fd()
Returns the file descriptor number associated with this object.
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.
groupgroup contains the address of the multicast group the
application wants to join. It must be a valid multicast address.
addressaddress is the address of the local interface with which
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 IP_ADD_MEMBERSHIP and IPPROTO_IPV6 IPV6_JOIN_GROUP.
The address parameter is currently not supported for IPv6.
This function did not support IPv6 in Pike 7.8 and earlier.
drop_membership()
UDP bind(int|string port, string|void address, string|bool no_reuseaddr)
Binds a port for receiving or transmitting UDP.
portEither a port number or the name of a service as listed in /etc/services.
addressLocal address to bind to.
no_reuseaddrIf set to 1, Pike will not set the SO_REUSEADDR option
on the UDP port.
SO_REUSEADDR is never applied when binding a random port
(bind(0)).
In general, SO_REUSEADDR is not desirable on UDP ports.
Unless used for receiving multicast, be sure to never bind a
non-random port without setting no_reuseaddr to 1.
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.
groupgroup contains the address of the multicast group the
application wants to join. It must be a valid multicast address.
addressaddress is the address of the local interface with which
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 IP_DROP_MEMBERSHIP and IPPROTO_IPV6 IPV6_LEAVE_GROUP.
The address parameter is currently not supported for IPv6.
This function did not support IPv6 in Pike 7.8 and earlier.
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.
reply_addressLocal address that should appear in the multicast packets.
See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_IF and IPPROTO_IPV6 IPV6_MULTICAST_IF.
This function did not support IPv6 in Pike 7.8.
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 _Stdio.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
int query_fd()
Gets the file descriptor for this UDP port.
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.
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()
UDP set_fd(int fd)
Use the file descriptor fd for UDP.
bind
int set_multicast_ttl(int ttl)
Set the time-to-live value of outgoing multicast packets for this socket.
ttlThe number of router hops sent multicast packets should survive.
It is very important for multicast packets to set the smallest TTL possible. The default before calling this function is 1 which means that multicast packets don't leak from the local network unless the user program explicitly requests it.
See also the Unix man page for setsocketopt IPPROTO_IP IP_MULTICAST_TTL and IPPROTO_IPV6 IPV6_MULTICAST_HOPS.
This function did not support IPv6 in Pike 7.8 and earlier.
add_membership()
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 equivalent 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 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 int Stdio.PROP_TTY
The Stdio.File object supports tty operations.
This constant is only present on platforms where pseudo tty (aka pty) operations are available, and may thus be used to detect whether such operations should be attempted.
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.
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 _Stdio : _Stdio
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 regular 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()
local typedeffunction(mixed|void, string:int|void)|function(mixed|void, Buffer:int|void)|function(mixed|void:int|void) Stdio.read_callback_t
The various read_callback signatures.
The string (or void) version is used when buffer mode (see
set_buffer_mode) has not been enabled for reading.
The Buffer version is used when a Buffer has been enabled
for reading.
In both cases the data is the newly arrived data, but in buffered mode data you did not fully read in the last read callback is kept in the buffer.
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.
The low-level sending may be performed with blocking I/O calls, and
thus trigger the process being killed with SIGPIPE when the
peer closes the other end. Add a call to signal() to avoid this.
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()
local typedeffunction(mixed|void:int|void)|function(mixed|void, Buffer:int|void) Stdio.write_callback_t
The various write_callback signatures.
The void version is used when buffer mode (see
set_buffer_mode) has not been enabled for writing.
The Buffer version is used when a Buffer has been enabled
for writing, add data to that buffer to send it.
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
int seek(int to, string|void how)
int tell()
A buffer to use as input or buffering when doing I/O. It is
similar to String.Buffer, but can only contain 8bit data and is
designed for protocol parsing. It is optimized for reading from
the beginning and adding to the end, and will try to minimize the
amount of data copying that is done.
The class maintains two separate offsets, one for reading and one for writing. The functions that add data all do so at the write offset (the end of the buffer), and reading is done from the read offset (the start of the buffer).
The class can also be used to directly read from and write to filedescriptors if so desired. This eliminates at least one memory copy.
The "avoid copy" part means that a Buffer will never shrink
unless you call the trim function.
int __fd_set_output(object|function(string:int) write_callback)
This tells the buffer to trigger the write callback for the specified filedescriptor when data is added to the buffer.
This is used internally by Stdio.File to handle nonblocking buffered mode, and is not really intended to be used directly.
If write_callback is 0 (zero) the state is cleared.
string(8bit) encode_value(Stdio.Buffer data)
Stdio.Buffer decode_value(string(8bit) data)
Encode and decode Stdio.Buffer objects. Only the buffer data is kept, no other state is saved.
int(-1..) search(Stdio.Buffer from, int(8bit) character, int|void start, int(0..)|void end)
Search forward from the indicated start position for the specified
character.
characterCharacter to search for.
startStart position relative to the current read position of the buffer.
Negative start values are supported and indicate positions
prior to the current read position.
endDon't search past this position of the buffer.
Returns the first found position of character relative to the
current read position of the buffer on success, and UNDEFINED
on not found. The read position is not advanced.
read_cstring(), search(), lfun::_search()
int(-1..) search(Stdio.Buffer from, string(8bit) substring, int|void start, int|void end)
Search forward from the indicated start position for the specified
substring.
substringSubstring to search for.
startStart position relative to the current read position of the buffer.
Negative start values are supported and indicate positions
prior to the current read position.
endDon't search past this position of the buffer.
Returns the first found position of substring relative to the
current read position of the buffer on success, and UNDEFINED
on not found. The read position is not advanced.
read_cstring(), search(), lfun::_search()
int sizeof( Stdio.Buffer arg )
Returns the buffer size, in bytes. This is how much you can read from the buffer until it runs out of data.
int res = Stdio.Buffer()[ off ]
Return the character at the specified offset.
Stdio.Buffer()[ off ] = char
Set the character at the specified offset to char.
Buffer add(AddArgument ... data)
private typedef System.Memory|Stdio.Buffer|String.Buffer BufferObject;
private typedef BufferObject|string(8bit)|int(8bit)|array(AddArgument) AddArgument;Add the items in data to the end of the buffer.
The supported argument types are:
| An eight bit string. |
| A single byte |
| A chunk of memory. The whole memory area is added. |
| A chunk of memory. The whole memory area is added. |
| A chunk of memory. The whole memory area is added. |
| Add all elements in the array individually. Each element may be any one of the types listed here. |
sprintf, add_int8, add_int16, add_int32, add_int
and
add_hstring
Buffer add_hint(int i, int(0..) size_width)
First add the size of the integer when encoded to base 256 as a
size_width integer, then add the integer to the buffer, both
in network byte order.
size_width must be less than Int.NATIVE_MAX.
Buffer add_hstring(string(8bit) data, int size_size)
Buffer add_hstring(Stdio.Buffer data, int size_size)
Buffer add_hstring(System.Memory data, int size_size)
Buffer add_hstring(String.Buffer data, int size_size)
Buffer add_hstring(int(8bit) data, int size_size)
Buffer add_hstring(array data, int size_size)
Buffer add_hstring(int|string(8bit)|Stdio.Buffer|System.Memory|array data, int size_size, int offset)
Adds length of data followed by data to the buffer.
This is identical to sprintf("%"+size_size+"H",(string)Stdio.Buffer(data)) but significantly faster.
size_size is the number of bytes used to represent the length of the data.
It must be less than Int.NATIVE_MAX.
offset is added to the length of the data prior to writing out
the length. Typical usage involves adding size_size to account
for the room used by the size.
The supported data argument types are
| An eight bit character. |
| An eight bit string. |
| A chunk of memory. The whole memory area is added. |
| A chunk of memory. The whole memory area is added. |
| A chunk of memory. The whole memory area is added. |
| Add all elements in the array individually. Each element may be any one of the types listed here. |
Buffer add_int(int i, int(0..) width)
Adds a generic integer to the buffer as an (width*8)bit network byteorder number.
width must be less than Int.NATIVE_MAX.
Buffer add_int16(int(16bit))
Add a 16-bit network byte order value to the buffer
Buffer add_int32(int i)
Adds a 32 bit network byte order value to the buffer
Buffer add_int8(int(8bit))
Adds a single byte to the buffer.
Buffer add_ints(array(int) integers, int(8bit) len)
Add the integers in the specified array, len bytes per int.
Equivalent to calling add_int for each integer, but faster,
and if an error occurs the buffer will contain no new
data. Either all or none of the integers will be added.
Errors can occur if one of the elements in integers is not
actually an integer, if sizeof(integers)*len is bigger than can
be represented in a size_t, or if the buffer cannot grow due to
an out of memory condition.
Buffer add_padding(int(0..) nbytes, int(8bit)|void byte)
Add nbytes bytes of padding, if byte is not specified the
area will be filled with 0's, otherwise the specified byte will
be repeated.
(string)Stdio.Buffer()
Convert the buffer to a string.
This only works for buffers whose length is less than 0x7fffffff.
void clear()
Clear the buffer.
int(0..)|int(-1..-1) consume(int(0..) n)
Discard the first n bytes from the buffer
Returns -1 on error and the amount of space still left otherwise.
Stdio.Buffer Stdio.Buffer(int|void len)
Stdio.Buffer Stdio.Buffer(string(8bit) contents)
Stdio.Buffer Stdio.Buffer(System.Memory|String.Buffer contents)
If passed an integer or no argument, create a buffer of that size, or if no argument is given, 226 bytes.
If contents are specified a new buffer with the contents of
the given string/System.Memory or String.Buffer will be created.
In the String.Buffer case the data has to be copied unless
there is only one reference to the String.Buffer object, since
modifications of the String.Buffer would cause the Buffer to
point into invalid memory.
In all other cases this will not copy the string data, instead data will be read from the source until it needs to be modified, so the buffer creation is fast regardless of the length of the string.
However, as an example, if the buffer is created with a 100Gb
System.Memory mmap:ed file as the contents and you later on
try to modify the buffer using one of the add functions (or
sprintf and similar) the old contents will be copied.
You can use read_only() to avoid accidents.
int(-1..) input_from(Stdio.Stream f, int|void nbytes)
Read data from f into this buffer. If nbytes is not
specified, read until there is no more data to read (currently).
Returns the amount of data that was read, or -1 on
read error.
Please note that this funcition will read all data from the filedescriptor unless it's set to be non-blocking.
object lock()
Makes this buffer read only until the returned object is released.
This currently simply returns a 0-length subbuffer.
mixed match(string(8bit) format)
Reads data from the beginning of the buffer to match the specifed format, then return the match.
The non-matching data will be left in the buffer.
This function is very similar to sscanf, but the
result is the sum of the matches. Most useful to match
a single value.
// get the next whitespace separated word from the buffer. buffer->match("%*[ \t\r\n]%[^ \t\r\n]");
int(-1..) output_to(Stdio.Stream|function(string:int) fun, int(0..)|void nbytes)
Write data from the buffer to the indicated file.
funWrite function. Either one of:
| A file object in which the function |
| A function which will be called with a |
nbytesIf nbytes is not specified the whole buffer will be written
if possible. Otherwise at most nbytes will be written.
Will return the number of bytes that have been written successfully.
If no bytes have been written successfully and fun() failed
with an error, -1 will be returned.
protected bool range_error(int howmuch)
This function is called when an attempt is made to read out of bounds.
The default implementation simply returns 0 (zero).
Override this function to change the behavior.
howmuchThe argument howmuch indicates how much data is needed:
| Need |
| The amount of data needed is not certain.
This most often happens when |
| Tried to The only supported way is to extract the data from the buffer,
add the requested amount of "go backbuffer", add the data
back, and forward - |
true if the operation should be retried, false otherwise.
Do not return true unless you have added data to the buffer, doing so could result in an infinite loop (since no data is added, the range_error will be called again immediately).
string(8bit) read(int n)
Read n bytes of data from the buffer.
If there is not enough data available this returns 0.
try_read()
string(8bit) read()
Read all data from the buffer.
If there is not enough data available this returns 0.
This is basically equivalent to (string)buffer, but it also removes the data from the buffer.
try_read()
Buffer read_buffer(int n)
Buffer read_buffer(int n, bool copy)
Same as read, but returns the result as an Buffer.
No data is copied unless copy is specified and true, the new buffer
points into the old one.
As long as the subbuffer exists no data can be added to the main buffer.
Usually this is OK, since it often represents something that should be parsed before the next whatever is extracted from the buffer, but do take care.
string(8bit) read_cstring()
Reads a \0 terminated C-string and returns the string excluding the terminating \0.
If there is not enough data available return UNDEFINED.
Note that pike string can not be longer than 0x7fffffff bytes (~2Gb).
_search()
Buffer read_hbuffer(int n)
Buffer read_hbuffer(int n, bool copy)
Same as read_hstring, but returns the result as an Buffer.
No data is copied unless copy is specified and true, the new
buffer points into the old one.
As long as the subbuffer exists no data can be added to the main buffer.
Usually this is OK, since it often represents something that should be parsed before the next whatever is extracted from the buffer, but do take care.
If you need to unlink the new buffer after it has been
created, call trim in it.
int read_hint(int n)
Read a network byte order unsigned number of size n*8 bits, then read another network byte order number of the size indicated by the first size.
Will return -1 if there is not enough buffer space available unless error mode is set to throw errors.
string(8bit) read_hstring(int(0..) n, void|int offset)
Identical in functionality to read(read_number(n)) but
faster.
Read a network byte order number of size n*8 bits, then return the indicated number of bytes as a string.
offset is substracted from the specified length prior to reading the
string. Typical usage involves substracting n to account
for the room used by the size.
If there is not enough data available return 0.
Note that pike string can not be longer than 0x7fffffff bytes (~2Gb).
int read_int(int n)
Read a network byte order unsigned number of size n*8 bits, then return it.
Will return -1 if there is not enough buffer space available unless error mode is set to throw errors.
int(16bit) read_int16()
int(24bit) read_int24()
int(32bit) read_int32()
int(8bit) read_int8()
array(int) read_ints(int n, int width)
Read a list of n network byte order unsigned numbers each of
size width*8 bits, then return it.
Will return 0 if there is not enough buffer space available unless error mode is set to throw errors.
mixed read_json(int|void require_whitespace_separator)
Read a single JSON expression from the buffer and return it.
If require_whitespace_separator is true there must be a whitespace
after each json value (as an example, newline or space).
The JSON is assumed to be utf-8 encoded.
UNDEFINED if no data is available to read. The read value otherwise.
Unless whitespaces are required this function only really work correctly with objects, arrays and strings.
There is really no way to see where one value starts and the other ends for most other cases
void read_only()
Make the buffer permanently read only.
You can use lock() to do this temporarily.
int read_sint(int size)
Read a network byte order two:s complement signed number of size n*8 bits, then return it.
Will return UNDEFINED if there is not enough buffer space available unless error mode is set to throw errors.
RewindKey rewind_on_error()
RewindKey rewind_key()
These functions are very similar. The rewind_on_error edition
will create an object that, when it goes out of scope without
having been destructed explicitly, will cause the buffer to
rewind to the location it had when this function is called.
This will happen if you throw an error or otherwise let the object fall out of scope.
Use destruct(RewindKey) or RewindKey.release to stop the
buffer from being rewound.
The second version (rewind_key) requires you to explicitly
call RewindKey.rewind to do the rewind.
Take some care with these objects, if you create multiple ones at once the results might be somewhat confusing if you do not release them in the reverse order they were created in (then again, you almost certainly really only need one)
You can call RewindKey.update in the generated object to
change where it will be rewound to.
The typical use-case of this functionality is when parsing a packet protocol with variable length packets where the length is not immediately known. It saves you from keeping track of how much to rewind if you had not actually gotten the whole packet yet.
void parse_packet( Stdio.Buffer b ) { Stdio.Buffer.RewindKey rewind = b->rewind_on_error(); b->set_error_mode(1); switch( b->read_int8() ) // packet type { case DATA: int channel = b->read_int8(); Stdio.Buffer data = b->read_hbuffer( 4 ); // we have read the whole packet, so no longer rewind on error. rewind->release(); return handle_data_packet( channel, data ); } }
Just calling rewind_on_error without assigning the return
value to something will not do anything. You need to keep the
object around while the rewind-to position is still valid.
Keeping the object around forbids the buffer from moving data inside itself, this means that it can only grow. So do not keep the rewind key when it is not needed.
Buffer set_error_mode(int m)
Buffer set_error_mode(program m)
Set the error mode of this buffer to m.
If true operations that would normally return 0 (like trying to
read too much) will instead throw an error. If m is a program
a clone of it will be thrown on error.
This is useful when parsing received data, you do not have to verify that each and every read operation suceeds.
However, the non-error mode is more useful when checking to see if a packet/segment/whatever has arrived.
The thrown error object will have the constant buffer_error set to a non-false value.
void read_callback(int i, string new_data) { inbuffer->add( new_data ); while( Buffer packet = inbuffer->read_hbuffer(2) ) { packet->set_error_mode(Buffer.THROW_ERROR); if( mixed e = catch( handle_packet( packet ) ) ) if( e->buffer_error ) protocol_error(); // illegal data in packet else throw(e); // the other code did something bad } } void handle_packet( Buffer pack ) { switch( pack->read_int8() ) { ... case HEADER_FRAME: int num_headers = pack->read_int32(); for( int i = 0; i<num_headers; i++ ) headers[pack->read_hstring(2)] = pack->read_hstring(2); ... } }
void set_max_waste(float factor)
Configure how much free space should be allowed, at most, as a factor of the current buffer size.
The default is 0.5, leaving at most half the buffer as waste.
Buffer sprintf(strict_sprintf_format format, sprintf_args ... args)
Appends the output from sprintf at the end of the buffer.
This is somewhat faster than add(sprintf(...)) since no intermediate string is created.
array sscanf(string(8bit) format)
Reads data from the beginning of the buffer to match the specifed format, then return an array with the matches.
The non-matching data will be left in the buffer.
See array_sscanf for more information.
void trim()
Frees unused memory.
Note that calling this function excessively will slow things down, since the data often has to be copied.
This function could possibly throw an out-of-memory error if the realloc fails to find a new (smaller) memory area.
int(0..)|int(-1..-1) truncate(int(0..) n)
Truncates the buffer to a length of n bytes.
Returns -1 on error and the number of bytes removed otherwise.
int(-1..) try_output()
Try to write some data from the buffer to the file
registered with __fd_set_output().
This is typically called from backend callbacks when it seems that it is possible to write some data to the file.
Returns -1 on write error, and otherwise
the number of bytes written to the file.
__fd_set_output()
string(8bit) try_read(int len)
Attempt to read some data from the buffer.
lenRead at most len bytes from the buffer.
If the buffer contains less than len bytes
of data, the entire buffer contents are returned.
Otherwise the first len bytes are returned.
read()
int(0..)|int(-1..-1) unread(int(0..) n)
Rewind the buffer n bytes.
This function returns how many more bytes of buffer is available to rewind, or -1 on error.
Unless you add new data to the buffer using any of the add functions you can always rewind.
You can call unread(0) to see how much.
The return value of Buffer.rewind_on_error() and
Buffer.rewind_key()
This object will cause the buffer to unwind to the position it was
at when the object was created either when it is released (when it
falls out of scope, explicit destruct does not count) or when
rewind is called, depending on which function was used to
create it.
void release()
Do not rewind if the object is released.
This is equivalent to calling destruct() on the object
void rewind()
Rewinds the buffer explicitly.
Destructs this RewindKey
void update()
Update the location the buffer will be rewound to to the current position of the buffer.
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, string|void how)
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()
Low level I/O operations.
This is not the class you want. Use Stdio.File and friends instead.
Stdio.File, Stdio.FILE, _Stdio.Fd_ref
protected int(0..) Stdio.Fd._errno
Variable containing the internal value returned by errno().
errno()
Fd Stdio.Fd._fd
Read only
mixed Stdio.Fd._read_callback
mixed Stdio.Fd._write_callback
mixed Stdio.Fd._read_oob_callback
mixed Stdio.Fd._write_oob_callback
mixed Stdio.Fd._fs_event_callback
Callback functions installed by Stdio.File()->set_callbacks() et al.
Stdio.File res = Stdio.Fd() << data
Stdio.File res = Stdio.Fd() << 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 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.
The default behaviour for sockets is typically to flush buffered
data in the background, but this can be changed with linger().
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.
linger(), 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)
string(8bit)|int(0..0) connect(string dest_addr, int dest_port, string|int(0..0) src_addr, int|int(0..0) src_port, string(8bit) data)
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.
If the data argument is included the socket will use
TCP_FAST_OPEN if available, if not the data will not be
sent. In the data case the function either returns the data
that has not been sent (only one packet can be sent with this
option) or 0 if the connection failed immediately.
Returns 1 or the remaining data 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.
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.
Stdio.Fd Stdio.Fd(string filename)
Stdio.Fd Stdio.Fd(string filename, string mode)
Stdio.Fd Stdio.Fd(string filename, string mode, int access)
Stdio.Fd Stdio.Fd(int fd)
Stdio.Fd Stdio.Fd(int fd, string mode)
See open().
open()
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()
Return the errno for the latest failed file operation.
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()
array(string) get_dir(string|void path)
Get directory contents relative to an open directory.
pathPath relative to the open directory. Defaults to the directory itself.
Returns an array of filenames.
Not available on all architectures, or in Pike 7.6 and earlier.
predef::get_dir(), statat(), openat(), unlinkat()
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.
Returns the filename of the corresponding pts.
This function is only available on some platforms.
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.
bool linger(int(-1..65535)|void seconds)
Set the socket linger behaviour on close().
seconds | Reset to default behaviour. This typically means that
|
| Terminate the connection immediately on |
| Have |
Returns 1 on success, and 0 (zero) on failure.
This operation is only valid on sockets.
This function was not available in Pike 7.8.775 and earlier.
close()
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()
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()
bool open_socket(int|void port, string|void addr, int|string|void family_hint)
Stdio.File openat(string filename)
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(-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)
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
int query_fd()
Returns the file descriptor number associated with this object.
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()
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 offset)
int seek(int offset, string whence)
The seek() function repositions the offset of the open file
associated with the file descriptor fd to the argument offset
according to the directive whence as follows:
| The offset is set to |
| The offset is set to its current location plus |
| The offset is set to the size of the file plus |
If whence is not specified it is SEEK_SET if offset is
positive, and if offset is negative SEEK_END.
The seek() function on most operating systems allows the file offset to be set beyond the end of the file (but this does not change the size of the file). If data is later written at this point, subsequent reads of the data in the gap (a "hole") return null bytes ('\0') until data is actually written into the gap.
Seeking file data and holes
Stdio.SEEK_DATA and Stdio.SEEK_HOLE are nonstandard extensions present in Linux, Solaris, FreeBSD, and DragonFly BSD; they are proposed for inclusion in the next POSIX revision.
| Adjust the file offset to the next location in the file greater than or equal to offset containing data. If offset points to data, then the file offset is set to offset. |
| Adjust the file offset to the next hole in the file greater than or equal to offset. If offset points into the middle of a hole, then the file offset is set to offset. If there is no hole past offset, then the file offset is adjusted to the end of the file (i.e., there is an implicit hole at the end of any file). |
In both of the above cases, seek() fails if offset points past the end of the file.
These operations allow applications to map holes in a sparsely allocated file. This can be useful for applications such as file backup tools, which can save space when creating backups and preserve holes, if they have a mechanism for discovering holes.
For the purposes of these operations, a hole is a sequence of zeros that (normally) has not been allocated in the underlying file storage. However, a filesystem is not obliged to report holes, so these operations are not a guaranteed mechanism for mapping the storage space actually allocated to a file. (Furthermore, a sequence of zeros that actually has been written to the underlying storage may or may not be reported as a hole.)
In the simplest implementation, a filesystem can support the operations by making SEEK_HOLE always return the offset of the end of the file, and making SEEK_DATA always return offset (i.e., even if the location referred to by offset is a hole, it can be considered to consist of data that is a sequence of zeros).
Upon successful completion, seek() returns the resulting offset
location as measured in bytes from the beginning of the file. On
error, the value (off_t) -1 is returned and errno is set to
indicate the error.
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__
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()
Sets this file to blocking operation.
This is the inverse operation of set_nonblocking().
set_nonblocking()
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_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()
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 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()
bool tcdrain()
Wait for transmission buffers to empty.
Returns 1 on success and 0 (zero) on failure.
tcflush()
bool tcflush(string|void flush_direction)
Flush queued terminal control messages.
flush_direction | Flush received but not read. |
| Flush written but not transmitted. |
| Flush both of the above. Default. |
Returns 1 on success and 0 (zero) on failure.
tcdrain()
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.
tcsetsize()
bool tcsendbreak(int|void duration)
Send a break signal.
durationDuration to send the signal for. 0 (zero) causes
a break signal to be sent for between 0.25 and 0.5 seconds.
Other values are operating system dependent:
The number of joined break signals as above.
The time in milliseconds.
The value is ignored.
The behavior is changed to be similar to tcdrain().
Returns 1 on success and 0 (zero) on failure.
bool tcsetsize(int rows, int cols)
Set the number of rows and columns for a terminal.
Returns 1 on success and 0 (zero) on failure.
tcgetattr(), tcsetattr()
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.
If there are any file descriptors that have been queued for sending
(with send_fd()), they will be sent.
dataData to write.
If data is an array of strings, they are written in sequence.
formatextrasIf 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.
Writes data and returns the number of bytes that were
actually written.
| The number of bytes successfully written to the OS buffers. This can be less than the size of the given data if eg:
|
| No bytes were written. This may be due to
|
| Something went wrong and no bytes were written. |
If everything went fine, a call to errno() directly afterwards
returns zero.
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 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()
Proxy class that contains stub functions
that call the corresponding functions in
Fd.
Used by Stdio.File.
This is not the class you want. Use Stdio.File and friends instead.
Stdio.File, Stdio.FILE, _Stdio.Fd
Fd Stdio.Fd_ref._fd
Object to which called functions are relayed.
inherit Fd : Fd
Fake inherit to propagate the documentation
from _Stdio.Fd.
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
void set_blocking()
NonblockingStream set_read_callback(function(:void) f, mixed ... rest)
NonblockingStream set_write_callback(function(:void) f, mixed ... rest)
NonblockingStream set_close_callback(function(:void) f, mixed ... rest)
NonblockingStream set_fs_event_callback(function(:void) f, int event_mask, mixed ... rest)
void set_nonblocking(function(:void) a, function(:void) b, function(:void) c, function(:void)|void d, function(:void)|void e)
optional NonblockingStream set_read_oob_callback(function(:void) f, mixed ... rest)
optional NonblockingStream set_write_oob_callback(function(:void) f, mixed ... rest)
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.
Time of last access in nanoseconds, added to atime to get sub-second time
Time of last modification in nanoseconds, added to mtime to get sub-second time
Time of last file status change in nanoseconds, added to ctime to get sub-second time
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.
(mapping(string:int))Stdio.Stat()
(array)Stdio.Stat()
Convert the stat object to a mapping or array.
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.
This class lists the minimum functionality guaranteed to exist in all Stream objects.
NonblockingStream, BlockFile, File, FILE
void close()
string read(int nbytes)
optional string read_oob(int nbytes)
optional int write_oob(string data)
optional mapping(string:int) tcgetattr()
optional int tcsetattr(mapping(string:int) attr, string|void when)
int write(string data)
Send headers + from_fd[off..off+len-1] + trailers to
to_fd asyncronously.
This is the low-level implementation, which has several limitations.
You probably want to use Stdio.sendfile() instead.
Stdio.sendfile()
Stdio.sendfile Stdio.sendfile(array(string) headers, object from, int offset, int len, array(string) trailers, object to, function(:void) callback, mixed ... args)
Low-level implementation of Stdio.sendfile().
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.
Don't use this class directly! Use Stdio.sendfile() instead.
In Pike 7.7 and later the callback function will be called
from the backend associated with to.
May use blocking I/O and thus trigger process being killed
with SIGPIPE when the other end closes the connection.
Add a call to signal() to avoid this.
Stdio.sendfile()