int access(string path, string|void mode)
access() checks if the calling process can access the file
path. Symbolic links are dereferenced.
modeThe mode specifies the accessibility checks to be performed, and
is either not specified or empty, in which case access() just tests
if the file exists, or one or more of the characters "rwx".
r, w, and x test whether the file exists and grants read, write, and execute permissions, respectively.
The check is done using the calling process's real UID and GID, rather than the effective IDs as is done when actually attempting an operation (e.g., open(2)) on the file. This allows set-user-ID programs to easily determine the invoking user's authority.
If the calling process is privileged (i.e., its real UID is zero), then an X_OK check is successful for a regular file if execute permission is enabled for any of the file owner, group, or other.
| When the file is accessible using the given permissions. | ||||||||||||
| When the file is not accessible, in which case
Other errors can occur, but are not directly related to the
requested path, such as |
errno(), Stdio.File
int cd(string s)
Change the current directory for the whole Pike process.
Returns 1 for success, 0 (zero) otherwise.
getcwd()
string getcwd()
Returns the current working directory.
cd()
array(string) get_dir(void|string dirname)
Returns an array of all filenames in the directory dirname, or
0 (zero) if the directory does not exist. When no
dirname is given, current work directory is used.
mkdir(), cd()
int mkdir(string dirname, void|int mode)
Create a directory.
If mode is specified, it's will be used for the new directory after
being &'ed with the current umask (on OS'es that support this).
Returns 0 (zero) on failure, 1 otherwise.
rm(), cd(), Stdio.mkdirhier()
int cp(string from, string to)
Copies the file from to the new position to. This is an
alias for Stdio.cp.
int mv(string from, string to)
Rename or move a file or directory.
If the destination already exists, it will be replaced.
Replacement often only works if to is of the same type as
from, i.e. a file can only be replaced by another file and so
on. Also, a directory will commonly be replaced only if it's
empty.
On some OSs this function can't move directories, only rename them.
Returns 0 (zero) on failure, 1 otherwise. Call
errno() to get more error info on failure.
rm()
int rm(string f)
Remove a file or directory.
Returns 0 (zero) on failure, 1 otherwise.
May fail with errno() set to EISDIR or ENOTDIR
if the file has changed to a directory during the call
or the reverse.
Stdio.File()->unlinkat(), mkdir(), Stdio.recursive_rm()
int file_truncate(string file, int length)
Truncates the file file to the length specified in length.
Returns 1 if ok, 0 if failed.
string basename(string path)
Returns the last segment of a path.
dirname(), explode_path()
string dirname(string path)
Returns all but the last segment of a path. Some example inputs and outputs:
| Expression | Value |
| dirname("/a/b") | "/a" |
| dirname("/a/") | "/a" |
| dirname("/a") | "/" |
| dirname("/") | "/" |
| dirname("") | "" |
basename(), explode_path()
string combine_path(string path, string ... paths)
string combine_path_unix(string path, string ... paths)
string combine_path_nt(string path, string ... paths)
string combine_path_amigaos(string path, string ... paths)
Concatenate a number of paths to a straightforward path without
any "//", "/.." or "/.". If any path
argument is absolute then the result is absolute and the
preceding arguments are ignored. If the result is relative then
it might have leading ".." components. If the last
nonempty argument ends with a directory separator then the
result ends with that too. If all components in a relative path
disappear due to subsequent ".." components then the
result is ".".
combine_path_unix() concatenates in UNIX style, which also is
appropriate for e.g. URL:s ("/" separates path components and
absolute paths start with "/"). combine_path_nt()
concatenates according to NT filesystem conventions ("/" and "\"
separates path components and there might be a drive letter in
front of absolute paths). combine_path_amigaos() concatenates
according to AmigaOS filesystem conventions.
combine_path() is equivalent to combine_path_unix() on UNIX-like
operating systems, and equivalent to combine_path_nt() on NT-like
operating systems, and equivalent to combine_path_amigaos() on
AmigaOS-like operating systems.
getcwd(), Stdio.append_path()
array(string) explode_path(string p)
Split a path p into its components.
This function divides a path into its components. This might seem like
it could be done by dividing the string on <tt>"/"</tt>, but that will
not work on some operating systems. To turn the components back into
a path again, use combine_path().
Stdio.Stat file_stat(string path, void|bool symlink)
Stat a file.
If the argument symlink is 1 symlinks will not be followed.
If the path specified by path doesn't exist 0 (zero) will
be returned.
Otherwise an object describing the properties of path will be
returned.
In Pike 7.0 and earlier this function returned an array with 7 elements. The old behaviour can be simulated with the following function:
array(int) file_stat(string path, void|int(0..1) symlink)
{
File.Stat st = predef::file_stat(path, symlink);
if (!st) return 0;
return (array(int))st;
}
Stdio.Stat, Stdio.File->stat()
mapping(string:int) filesystem_stat(string path)
Returns a mapping describing the properties of the filesystem
containing the path specified by path.
If a filesystem cannot be determined 0 (zero) will be returned.
Otherwise a mapping(string:int) with the following fields will be returned:
| Size in bytes of the filesystem blocks. |
| Size of the entire filesystem in blocks. |
| Number of free blocks in the filesystem. |
| Number of available blocks in the filesystem.
This is usually somewhat less than the |
| Total number of files (aka inodes) allowed by this filesystem. |
| Number of free files in the filesystem. |
| Number of available files in the filesystem.
This is usually the same as the |
| Name assigned to the filesystem. This item is not available on all systems. |
| Type of filesystem (eg |
Please note that not all members are present on all OSs.
file_stat()
This object is used to represent file status information
from e.g. file_stat().
It contains the following items usually found in a C struct stat:
File mode (see mknod(2)).
File size in bytes.
User ID of the file's owner.
Group ID of the file's owner.
Time of last access in seconds since 00:00:00 UTC, 1970-01-01.
Time of last data modification.
Time of last file status change.
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.
bool equal(Stdio.Stat from, mixed other)
Compare this object with another Stat object.
Returns 1 if other is a Stat object with the
same content, and 0 (zero) otherwise.
(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).
int errno()
This function returns the system error from the last file operation.
Note that you should normally use Stdio.File->errno() instead.
Stdio.File->errno(), strerror()
string strerror(int errno)
This function returns a description of an error code. The error
code is usually obtained from eg Stdio.File->errno().
On some platforms the string returned can be somewhat nondescriptive.
@Pike.Annotations.Implements(NonblockingStream)@Pike.Annotations.Implements(BlockFile)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
optional inherit Fd : Fd
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(7bit) host, int|string(7bit) port, function(int, __unknown__ ... :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 to open a socket, 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()
variant Concurrent.Future async_connect(string(7bit) host, int|string(7bit) port)
Opens a TCP connection asynchronously using a Concurrent Future object.
hostHostname or IP to connect to.
portPort number or service name to connect to.
Returns a Concurrent.Future that resolves into the
connection object at success.
int close()
int close(string(7bit) 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(7bit) host, int(0..)|string(7bit) port)
variant int connect(string(7bit) host, int(0..)|string(7bit) port, string(7bit) client, int(0..)|string(7bit) client_port)
variant string connect(string(7bit) host, int(0..)|string(7bit) port, string(8bit) data)
variant string|zero connect(string(7bit) host, int(0..)|string(7bit) port, int(0)|string(7bit) client, int(0..)|string(7bit) client_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.
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 advisable to retry without TCP_FAST_OPEN (and remember this fact)
This function returns 1 or the remaining data for success,
0 otherwise.
To use nonblocking mode, open_socket() and set_nonblocking()
(or equivalent) need to be called before this function.
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(),
open_socket(), ::connect()
int connect_unix(string(8bit) 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(8bit) filename)
Stdio.File Stdio.File(string(8bit) filename, string(7bit) mode)
Stdio.File Stdio.File(string(8bit) filename, string(7bit) mode, int mask)
Stdio.File Stdio.File(string(8bit) descriptorname)
Stdio.File Stdio.File(int fd)
Stdio.File Stdio.File(int fd, string(7bit) 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.
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(8bit) filename, string(7bit) mode)
int open(string(8bit) filename, string(7bit) 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(8bit)|void port, string(7bit)|void address, int|string(8bit)|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(8bit) filename)
File openat(string(8bit) filename, string(7bit) mode)
File openat(string(8bit) filename, string(7bit) mode, int mask)
Open a file relative to an open directory.
File.statat(), File.unlinkat()
int openpt(string(7bit) 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|zero 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)) 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()
read_oob_callback_t query_read_oob_callback()
write_oob_callback_t query_write_oob_callback()
close_callback_t query_close_callback()
array(function(mixed, void|string(8bit):int)|zero) 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)|zero 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(8bit)|zero) 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) in, Stdio.Buffer|int(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. If this buffer is non-empty, its contents will be returned after any already received data.
outOutput buffer. If this buffer is non-empty, its contents will be sent after any data already queued for sending.
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.
query_buffer_mode()
void set_callbacks(read_callback_t|void read_cb, write_callback_t|void write_cb, close_callback_t|void close_cb, read_oob_callback_t|void read_oob_cb, write_oob_callback_t|void 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(8bit):int)|zero read_cb)
void set_read_callback(function(mixed, Buffer:int)|zero read_cb)
void set_write_callback(function(mixed:int)|zero write_cb)
void set_write_callback(function(mixed, Buffer:int)|zero write_cb)
void set_read_oob_callback(function(mixed, string(8bit):int)|zero read_oob_cb)
void set_write_oob_callback(function(mixed:int)|zero write_oob_cb)
void set_close_callback(function(mixed:int)|zero close_cb)
void set_fs_event_callback(function(mixed, int:int)|zero 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, close_callback_t close_callback)
void set_nonblocking(read_callback_t read_callback, write_callback_t write_callback, close_callback_t close_callback, read_oob_callback_t read_oob_callback, write_oob_callback_t 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()
@Pike.Annotations.Implements(NonblockingStream)Stdio.FILE is a buffered version of Stdio.File, it inherits
Stdio.File and has most of the functionality of Stdio.File.
However, it has an input buffer that allows line-by-line input.
It also has support for automatic charset conversion for both input
and output (see Stdio.FILE()->set_charset()).
The output part of Stdio.FILE is currently not buffered.
inherit File : file
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|zero 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()
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.
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)|zero 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(8bit) filename)
FILE openat(string(8bit) filename, string(7bit) mode)
FILE openat(string(8bit) filename, string(7bit) 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(8bit)|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(-1..) write(array(string)|sprintf_format what, sprintf_args ... 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.
inherit _port : _port
File|zero 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, fd_factory()
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, and is equivalent to
creating a port and initializing it with listen_fd(0).
bind
protected Fd fd_factory()
Factory creating empty Fd objects.
This function is called by accept() when it needs to create
a new file.
The default implementation returns the Fd inherit in
an empty File object.
accept()
UDP (User Datagram Protocol) handling.
inherit _Stdio.UDP : UDP
UDP set_nonblocking()
UDP set_nonblocking(void|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)|zero 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()
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.
inherit TermMachine : TermMachine
array(string) Stdio.Terminfo.Termcap.aliases
Stdio.Terminfo.Termcap Stdio.Terminfo.Termcap(string cap, TermcapDB|void tcdb, int|void maxrecurse)
string tputs(string s)
Put termcap string
Termcap database
Terminfo terminal description object
inherit TermMachine : TermMachine
array(string) Stdio.Terminfo.Terminfo.aliases
Stdio.Terminfo.Terminfo Stdio.Terminfo.Terminfo(string filename)
string tputs(string s)
Document this function
Terminfo database for a single directory.
Terminal-aware line-based input.
// Get a Readline object connected to Stdio.stdin/Stdio.stdout. Stdio.Readline readline = Stdio.Readline();
// Enable history. string|zero history_dump = Stdio.read_file(history_file); if (history_dump) { readline->enable_history(history_dump/"\n"); } else { readline->enable_history(512); // 512 lines of history. }
// Add a completion handler. readline->get_input_controller()->bind("\t", handle_completions);
// Output some message. readline->message("Welcome to some application.\n");
// Set a prompt. readline->set_prompt("> ");
// Read some input. string command = readline->read();
// Save the history. Stdio.write_file(history_file, readline->get_history()->encode());
enable_history(), get_history(), get_input_controller(),
message(), read(), set_prompt()
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|zero edit(string data, string|void local_prompt, array(string)|void attrs)
Read a line of data from the input.
dataInitial/default value that the user may edit.
local_promptAlternative prompt. Defaults to the prompt set by set_prompt().
attrsAlternative prompt attributes. Defaults to the attributes set
by set_prompt().
read()
void enable_history(array(string)|History|int hist)
Enable/disable history.
hist | Disable history. |
| Enable history of max |
| Set the history to this array of lines. The maximum number of lines is set to 512. |
| Use this |
void eof()
Document this function
History get_history()
Get the currently active History object (if any).
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.
write()
string newline()
Document this function
array(int) pointmark()
Document this function
string read(string|void prompt, array(string)|void attrs)
Read a line of data from the input.
promptAlternative prompt. Defaults to the prompt set by set_prompt().
attrsAlternative prompt attributes. Defaults to the attributes set
by set_prompt().
This function is essentially a short hand for
edit("", prompt, attrs).
edit()
void redisplay(int clear, int|void nobackup)
Document this function
string region(int ... args)
Document this function
void set_blocking()
Disable nonblocking mode.
This is equivalent to calling set_nonblocking(0).
set_nonblocking()
void set_echo(int onoff)
Set text echo on or off.
onoff1 for echo, 0 for no echo.
void set_nonblocking(function(string|zero:void)|zero f)
Set a function to be called every time a line is completed.
fFunction to call when a line is completed, or 0 (zero) to
disable. It will be called with a string when a line is completed,
and 0 (zero) when eof() is called.
set_blocking(), read()
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)
Print a message to the output device with optional word wrap.
message()
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()
bool pop(string|void text)
Pop the last string off the history, discarding it. If text is provided, will only pop that string. Returns 1 if a string was removed, 0 if not.
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)|zero 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)|zero 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)
inherit _Stdio : _Stdio
local typedeffunction(mixed|void:int)|zero Stdio.close_callback_t
The type for close callback functions.
local typedeffunction(mixed|void, int:int)|zero Stdio.fs_event_callback_t
The type for fs_event callback function functions.
local typedeffunction(mixed|void, string:int|void)|function(mixed|void, Buffer:int|void)|function(mixed|void:int|void)|zero 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.
local typedeffunction(mixed|void, string|void:int)|zero Stdio.read_oob_callback_t
The type for read out of band callback functions.
local typedeffunction(mixed|void:int|void)|function(mixed|void, Buffer:int|void)|zero 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.
local typedeffunction(mixed|void:int)|zero Stdio.write_oob_callback_t
The type for write out of band callback functions.
final constantint Stdio.DATA_CHUNK_SIZE
Size used in various places to divide incoming or outgoing data into chunks.
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.
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()
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(7bit) 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(8bit) 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()
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()
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).
void werror(string s)
Write a message to stderr. Stderr is normally the console, even if the process output has been redirected to a file or pipe.
This function is identical to predef::werror().
predef::werror()
int write_file(string filename, string str, int|void access)
Write the string str onto the file filename. Any existing
data in the file is overwritten.
For a description of access, see Stdio.File()->open().
Throws an error if filename couldn't be opened for writing.
Returns the number of bytes written, i.e. sizeof(str).
append_file(), read_bytes(), Stdio.File()->open()
@Pike.Annotations.Implements(InputBlockFile)@Pike.Annotations.Implements(Stream)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, InputBlockStream, File, FILE
__generic__ string StringType = string(8bit)
inherit InputBlockFile(< StringType >) : InputBlockFile
inherit OutputStreamMixin(< StringType >) : OutputStreamMixin
@Pike.Annotations.Implements(Stdio.BlockFile)@Pike.Annotations.Implements(Stdio.NonblockingStream)A string wrapper that pretends to be a Stdio.File object
in addition to some features of a Stdio.FILE object.
constant int Stdio.FakeFile.is_fake_file
This constant can be used to distinguish a FakeFile object
from a real 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|zero gets()
Stdio.FILE()->gets()
String.SplitIterator line_iterator(int|void trim)
Stdio.File()->line_iterator()
int(-1..1) peek(int|float|void timeout)
Stdio.File()->peek()
string|zero query_address(void|bool is_local)
Always returns 0.
Stdio.File()->query_address()
function(:void)|zero query_close_callback()
Stdio.File()->query_close_callback
mixed query_id()
Stdio.File()->query_id()
function(:void)|zero query_read_callback()
Stdio.File()->query_read_callback
function(:void)|zero query_read_oob_callback()
Stdio.File()->query_read_oob_callback
function(:void)|zero query_write_callback()
Stdio.File()->query_write_callback
function(:void)|zero query_write_oob_callback()
Stdio.File()->query_write_oob_callback
string|zero 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(Stdio.close_callback_t cb)
Stdio.File()->set_close_callback
void set_id(mixed _id)
Stdio.File()->set_id()
bool set_nodelay(bool|void state)
Stdio.File()->set_nodelay
void set_nonblocking(Stdio.read_callback_t rcb, Stdio.write_callback_t wcb, Stdio.close_callback_t ccb, void|Stdio.read_oob_callback_t rocb, void|Stdio.write_oob_callback_t wocb)
Stdio.File()->set_blocking
void set_nonblocking_keep_callbacks()
Stdio.File()->set_blocking_keep_callbacks
void set_read_callback(Stdio.read_callback_t cb)
Stdio.File()->set_read_callback
void set_read_oob_callback(Stdio.read_oob_callback_t cb)
Stdio.File()->set_read_oob_callback
void set_write_callback(Stdio.write_callback_t cb)
Stdio.File()->set_write_callback
void set_write_oob_callback(Stdio.write_oob_callback_t cb)
Stdio.File()->set_write_oob_callback
Stdio.Stat stat()
Returns size and the creation time of the string.
int(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()
This module emulates a bidirectional pipe/socket without using any actual file descriptors.
inherit InternalSocket : InternalSocket
Stdio.FakePipe Stdio.FakePipe(void|string direction)
Class that implements one end of an emulated bi-directional pipe/socket.
protected this_program|zero Stdio.FakePipe.InternalSocket._other
Stdio.Buffer|zero Stdio.FakePipe.InternalSocket._read_buffer
Stdio.Buffer|zero Stdio.FakePipe.InternalSocket._write_buffer
protected Thread.Mutex Stdio.FakePipe.InternalSocket.mux
protected Thread.Condition Stdio.FakePipe.InternalSocket.cond
this_program Stdio.FakePipe.InternalSocket.other
The other end of the emulated pipe/socket.
Read only
protected local void __create__(this_program|zero _other, Stdio.Buffer|zero _read_buffer, Stdio.Buffer|zero _write_buffer, Thread.Mutex mux, Thread.Condition cond)
int close(string|void direction)
Stdio.FakePipe.InternalSocket Stdio.FakePipe.InternalSocket(this_program|zero _other, Stdio.Buffer|zero _read_buffer, Stdio.Buffer|zero _write_buffer, Thread.Mutex mux, Thread.Condition cond)
int errno()
function(:void) get_close_callback()
mixed get_id()
function(:void) get_read_callback()
function(:void) get_write_callback()
bool is_open(string|void direction)
int(-1..1) peek(int|float|void timeout, int|void not_eof)
Pike.Backend query_backend()
string(8bit) read(int|void nbytes, bool|void not_all)
void set_backend(Pike.Backend be)
void set_blocking()
void set_callbacks(function(:void) rcb, function(:void) wcb, function(:void) ccb)
void set_close_callback(function(:void) ccb)
void set_id(mixed id)
void set_nonblocking(function(:void) rcb, function(:void) wcb, function(:void) ccb)
void set_nonblocking_keep_callbacks()
void set_read_callback(function(:void) rcb)
void set_write_callback(function(:void) wcb)
int write(sprintf_format|array(string(8bit)) data, sprintf_args ... args)
constant Stdio.FakePipe.InternalSocket.STATE_BLOCKING
constant Stdio.FakePipe.InternalSocket.STATE_NONBLOCKING
@Pike.Annotations.Implements(InputStream)The Stdio.InputBlockFile API.
This class exists purely for typing reasons.
Use in types in place of Stdio.File where only blocking
I/O in the read direction is done with the object.
InputStream, NonblockingInputStream, BlockFile, File, FILE
__generic__ string StringType = string(8bit)
inherit InputStream(< StringType >) : InputStream
int seek(int to, string(7bit)|void how)
int tell()
The Stdio.InputStream API.
This class exists purely for typing reasons.
Use in types in place of Stdio.File where only blocking
stream-oriented I/O in the read direction is done with the object.
This class lists the minimum functionality guaranteed to exist in all Stream objects that are opened for reading.
Stream, NonblockingInputStream, InputBlockFile, File, FILE
__generic__ string StringType = string(8bit)
int close()
Close the stream.
StringType|zero read(int(0..)|void nbytes)
function(:StringType|zero) 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.
optional StringType|zero read_oob(int(0..)|void nbytes)
optional mapping(string(7bit):int)|zero tcgetattr()
optional int tcsetattr(mapping(string(7bit):int) attr, string(7bit)|void when)
@Pike.Annotations.Implements(InputStream)The Stdio.NonblockingInputStream 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.
InputStream, NonblockingStream, InputBlockFile, File, FILE
__generic__ string StringType = string(8bit)
inherit InputStream(< StringType >) : InputStream
void set_blocking()
void set_blocking_keep_callbacks()
void set_read_callback(read_callback_t f)
void set_close_callback(close_callback_t f)
optional void set_fs_event_callback(fs_event_callback_t f, int event_mask)
bool set_nodelay(bool|void state)
void set_nonblocking(read_callback_t a, write_callback_t b, close_callback_t c, read_oob_callback_t|void d, write_oob_callback_t|void e)
void set_nonblocking_keep_callbacks()
optional void set_read_oob_callback(read_oob_callback_t f)
Mixin for converting a NonblockingInputStream
into a NonblockingStream.
This class exists purely for typing reasons.
Typically you will not want to use this class directly, but instead use one of the classes that inherits it.
NonblockingInputStream, NonblockingStream
__generic__ string StringType = string(8bit)
inherit OutputStreamMixin(< StringType >) : OutputStreamMixin
void set_write_callback(write_callback_t f)
optional void set_write_oob_callback(write_oob_callback_t f)
@Pike.Annotations.Implements(Stream)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, NonblockingInputStream, BlockFile, File, FILE
__generic__ string StringType = string(8bit)
inherit NonblockingInputStream(< StringType >) : NonblockingInputStream
inherit NonblockingOutputStreamMixin(< StringType >) : NonblockingOutputStreamMixin
Mixin for converting an InputStream into a Stream.
This class exists purely for typing reasons.
Typically you will not want to use this class directly, but instead use one of the classes that inherits it.
InputStream, Stream, BlockFile
__generic__ string StringType = string(8bit)
int(-1..) write(StringType data)
optional int(-1..) write_oob(StringType data)
@Pike.Annotations.Implements(InputStream)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.
InputStream, NonblockingStream, BlockFile, File, FILE
__generic__ string StringType = string
inherit InputStream(< StringType >) : InputStream
inherit OutputStreamMixin(< StringType >) : OutputStreamMixin
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()
This module provides a generic data processing non-blocking pipe interface. Set it to a pool of dedicated backends to use more than one CPU core (use one thread per backend). Use it in conjunction with the Shuffler to scale to an unlimited number of CPU cores.
object Stdio.Pipe.Base.engine
Read only
final int close()
Stdio.Pipe.Base Stdio.Pipe.Base(Gz.deflate|void engine)
Note that the Gz.deflate engine provided needs to be preconfigured using negative compression levels.
protected void process_data(string(8bit) data)
protected string(8bit) process_header(string(8bit) data)
protected void process_init()
protected void process_trailer()
final void set_backend(Pike.Backend _backend)
final void set_close_callback(function(:void) ccb)
final void set_nonblocking(function(:void) rcb, function(:void) wcb, function(:void) ccb)
final void set_nonblocking_keep_callbacks()
final void set_read_callback(function(:void) rcb)
final void set_write_callback(function(:void) wcb)
final int write(string(8bit) data)
This module provides a gzip-uncompressing non-blocking pipe interface.
inherit .Base : Base
This module provides a gzip-compressing non-blocking pipe interface. Set it to a pool of dedicated backends to use more than one CPU core to compress data (use one thread per backend). Use it in conjunction with the Shuffler to scale to an unlimited number of CPU cores.
inherit .Base : Base