9. I/O
9.1. File system manipulation
- Methodaccess
int
access(string
path
,string
|void
mode
)- Description
access() checks if the calling process can access the file
path
. Symbolic links are dereferenced.- Parameter
mode
The
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.
- Returns
1
When the file is accessible using the given permissions.
0
When the file is not accessible, in which case
errno
is set to one of the following values:EACCESS
Access denied.
ELOOP
Too many symbolic links.
ENAMETOOLONG
The path is too long.
ENOENT
The file does not exist.
ENOTDIR
One of the directories used in
path
is not, in fact, a directory.EROFS
The filesystem is read only and write access was requested.
Other errors can occur, but are not directly related to the requested path, such as
ENOMEM
, etc.- See also
errno()
,Stdio.File
- Methodcd
int
cd(string
s
)- Description
Change the current directory for the whole Pike process.
- Returns
Returns
1
for success,0
(zero) otherwise.- See also
getcwd()
- Methodget_dir
array
(string
) get_dir(void
|string
dirname
)- Description
Returns an array of all filenames in the directory
dirname
, or0
(zero) if the directory does not exist. When nodirname
is given, current work directory is used.- See also
mkdir()
,cd()
- Methodmkdir
int
mkdir(string
dirname
,void
|int
mode
)- Description
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
Returns
0
(zero) on failure,1
otherwise.- See also
rm()
,cd()
,Stdio.mkdirhier()
- Methodcp
int
cp(string
from
,string
to
)- Description
Copies the file
from
to the new positionto
. This is an alias forStdio.cp
.
- Methodmv
int
mv(string
from
,string
to
)- Description
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 asfrom
, 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
Returns
0
(zero) on failure,1
otherwise. Callerrno()
to get more error info on failure.- See also
rm()
- Methodrm
int
rm(string
f
)- Description
Remove a file or directory.
- Returns
Returns
0
(zero) on failure,1
otherwise.- Note
May fail with
errno()
set toEISDIR
orENOTDIR
if the file has changed to a directory during the call or the reverse.- See also
Stdio.File()->unlinkat()
,mkdir()
,Stdio.recursive_rm()
- Methodfile_truncate
int
file_truncate(string
file
,int
length
)- Description
Truncates the file
file
to the length specified inlength
.- Returns
Returns 1 if ok, 0 if failed.
9.2. Path manipulation
- Methodbasename
string
basename(string
path
)- Description
Returns the last segment of a path.
- See also
dirname()
,explode_path()
- Methoddirname
string
dirname(string
path
)- Description
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("") "" - See also
basename()
,explode_path()
- Methodcombine_path
Methodcombine_path_unix
Methodcombine_path_nt
Methodcombine_path_amigaos 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
)- Description
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 tocombine_path_unix()
on UNIX-like operating systems, and equivalent tocombine_path_nt()
on NT-like operating systems, and equivalent tocombine_path_amigaos()
on AmigaOS-like operating systems.- See also
getcwd()
,Stdio.append_path()
- Methodexplode_path
array
(string
) explode_path(string
p
)- Description
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()
.
9.3. Status
- Methodfile_stat
Stdio.Stat
file_stat(string
path
,void
|bool
symlink
)- Description
Stat a file.
If the argument
symlink
is1
symlinks will not be followed.- Returns
If the path specified by
path
doesn't exist0
(zero) will be returned.Otherwise an object describing the properties of
path
will be returned.- Note
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;}
- See also
Stdio.Stat
,Stdio.File->stat()
- Methodfilesystem_stat
mapping
(string
:int
) filesystem_stat(string
path
)- Description
Returns a mapping describing the properties of the filesystem containing the path specified by
path
.- Returns
If a filesystem cannot be determined
0
(zero) will be returned.Otherwise a mapping(string:int) with the following fields will be returned:
"blocksize"
:int
Size in bytes of the filesystem blocks.
"blocks"
:int
Size of the entire filesystem in blocks.
"bfree"
:int
Number of free blocks in the filesystem.
"bavail"
:int
Number of available blocks in the filesystem. This is usually somewhat less than the
"bfree"
value, and can usually be adjusted with eg tunefs(1M)."files"
:int
Total number of files (aka inodes) allowed by this filesystem.
"ffree"
:int
Number of free files in the filesystem.
"favail"
:int
Number of available files in the filesystem. This is usually the same as the
"ffree"
value, and can usually be adjusted with eg tunefs(1M)."fsname"
:string
Name assigned to the filesystem. This item is not available on all systems.
"fstype"
:string
Type of filesystem (eg
"nfs"
). This item is not available on all systems. For some more uncommon filesystems this may be an integer representing the magic number for the filesystem type (cf statfs(2) on eg Linux systems).- Note
Please note that not all members are present on all OSs.
- See also
file_stat()
Class Stdio.Stat
- Description
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:
- mode
File mode (see mknod(2)).
- size
File size in bytes.
- uid
User ID of the file's owner.
- gid
Group ID of the file's owner.
- atime
Time of last access in seconds since 00:00:00 UTC, 1970-01-01.
- mtime
Time of last data modification.
- ctime
Time of last file status change.
- atime_nsec
Time of last access in nanoseconds, added to atime to get sub-second time
- mtime_nsec
Time of last modification in nanoseconds, added to mtime to get sub-second time
- ctime_nsec
Time of last file status change in nanoseconds, added to ctime to get sub-second time
- ino
Inode number.
- nlink
Number of links.
- dev
ID of the device containing a directory entry for this file.
- rdev
ID of the device.
It also contains some items that correspond to the C IS* macros:
- isreg
Set if the file is a regular file.
- isdir
Set if the file is a directory.
- islnk
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()
.- isfifo
Set if the file is a FIFO (aka named pipe).
- issock
Set if the file is a socket.
- ischr
Set if the file is a character device.
- isblk
Set if the file is a block device.
There are also some items that provide alternative representations of the above:
- type
The type as a string, can be any of
"reg"
,"dir"
,"lnk"
,"fifo"
,"sock"
,"chr"
,"blk"
, and"unknown"
.- mode_string
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 int
0
File mode, same as mode.
int
1
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.
int
2
Time of last access, same as atime.
int
3
Time of last data modification, same as mtime.
int
4
Time of last file status change, same as ctime.
int
5
User ID of the file's owner, same as uid.
int
6
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
clearsisreg
and settingmode_string
changes many of the other items.
- Method_equal
bool
equal(Stdio.Statfrom,mixed
other
)- Description
Compare this object with another
Stat
object.- Returns
Returns
1
ifother
is aStat
object with the same content, and0
(zero) otherwise.
- Methodcast
(
mapping
(string
:int
))Stdio.Stat()
(array
)Stdio.Stat()- Description
Convert the stat object to a mapping or array.
- Methodcreate
Stdio.StatStdio.Stat(
void
|object
|array
stat
)- Description
A new
Stdio.Stat
object can be initialized in two ways:stat
is an object, typically anotherStdio.Stat
. The stat info is copied from the object by getting the values ofmode
,size
,atime
,mtime
,ctime
,uid
,gid
,dev
,ino
,nlink
, andrdev
.stat
is a seven element array on the 'traditional' LPC stat-array form (see the class doc).
9.4. Error handling
- Methoderrno
int
errno()- Description
This function returns the system error from the last file operation.
- Note
Note that you should normally use
Stdio.File->errno()
instead.- See also
Stdio.File->errno()
,strerror()
- Methodstrerror
string
strerror(int
errno
)- Description
This function returns a description of an error code. The error code is usually obtained from eg
Stdio.File->errno()
.- Note
On some platforms the string returned can be somewhat nondescriptive.
9.5. Files and sockets
Class Stdio.File
- Annotations
@
Pike.Annotations.Implements
(NonblockingStream
)@
Pike.Annotations.Implements
(BlockFile
)- Description
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.- Note
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
ordup
). Objects do not contain cyclic references in themselves, so they will be destructed timely when they run out of references.- See also
Stdio.FILE
- Methodassign
int
assign(File
|Fd
o
)- Description
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.- See also
dup()
- Methodasync_connect
int
async_connect(string(7bit)
host
,int
|string(7bit)
port
,function
(int
,__unknown__
... :void
)callback
,mixed
...args
)- Description
Open a TCP/IP connection asynchronously.
This function is similar to
connect()
, but works asynchronously.- Parameter
host
Hostname or IP to connect to.
- Parameter
port
Port number or service name to connect to.
- Parameter
callback
Function to be called on completion. The first argument will be
1
if a connection was successfully established, and0
(zero) on failure. The rest of the arguments tocallback
are passed verbatim fromargs
.- Parameter
args
Extra arguments to pass to
callback
.- Returns
Returns
0
on failure to open a socket, and1
ifcallback
will be used.- Note
The socket may be opened with
open_socket()
ahead of the call to this function, but it is not required.- Note
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.- Note
The socket will be in nonblocking state if the connection is successful, and any callbacks will be cleared.
- See also
connect()
,open_socket()
,set_nonblocking()
- Methodasync_connect
variant
Concurrent.Future
async_connect(string(7bit)
host
,int
|string(7bit)
port
)- Description
Opens a TCP connection asynchronously using a Concurrent Future object.
- Parameter
host
Hostname or IP to connect to.
- Parameter
port
Port number or service name to connect to.
- Returns
Returns a
Concurrent.Future
that resolves into the connection object at success.
- Methodclose
int
close()int
close(string(7bit)
direction
)- Description
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.
- Returns
Nonzero is returned if the file wasn't open in the specified direction, zero otherwise.
- Note
This function will not call the close_callback.
- See also
open
,open_socket
- Methodconnect
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
)- Description
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
andclient_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 usewrite
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)
- Returns
This function returns 1 or the remaining
data
for success, 0 otherwise.- Note
In nonblocking mode
0
(zero) may be returned anderrno()
set toEWOULDBLOCK
orWSAEWOULDBLOCK
.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.
- See also
query_address()
,async_connect()
,connect_unix()
- Methodconnect_unix
int
connect_unix(string(8bit)
path
)- Description
Open a UNIX domain socket connection to the specified destination.
- Returns
Returns
1
on success, and0
on failure.- Note
Nonblocking mode is not supported while connecting
- Methodcreate
Stdio.FileStdio.File()
Stdio.FileStdio.File(
string(8bit)
filename
)Stdio.FileStdio.File(
string(8bit)
filename
,string(7bit)
mode
)Stdio.FileStdio.File(
string(8bit)
filename
,string(7bit)
mode
,int
mask
)Stdio.FileStdio.File(
string(8bit)
descriptorname
)Stdio.FileStdio.File(
int
fd
)Stdio.FileStdio.File(
int
fd
,string(7bit)
mode
)- Description
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 openmode
. This is the same thing as cloning and then callingopen()
, 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"
.- Note
Open mode will be filtered through the system UMASK. You might need to use
chmod()
later.- See also
open()
,connect()
,Stdio.FILE
,
- Methoddup
File
dup()- Description
This function returns a clone of Stdio.File with all variables copied from this file.
- Note
All variables, even id, are copied.
- See also
assign()
- Methoderrno
int
errno()- Description
Returns the error code for the last command on this file. Error code is normally cleared when a command is successful.
- Methodline_iterator
String.SplitIterator
|LineIterator
line_iterator(int
|void
trim
)- Description
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.
- Methodopen
int
open(string(8bit)
filename
,string(7bit)
mode
)int
open(string(8bit)
filename
,string(7bit)
mode
,int
mask
)- Description
Open a file for read, write or append. The parameter
mode
should contain one or more of the following letters:"r"
Open file for reading.
"w"
Open file for writing.
"a"
Open file for append (use with
"w"
)."t"
Truncate file at open (use with
"w"
)."c"
Create file if it doesn't exist (use with
"w"
)."x"
Fail if file already exists (use with
"c"
).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 is0666
(read+write for all in octal notation).- Returns
This function returns
1
for success,0
otherwise.- See also
close()
,create()
- Methodopen_socket
int
open_socket(int
|string(8bit)
|void
port
,string(7bit)
|void
address
,int
|string(8bit)
|void
family_hint
)- Description
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()
.- Parameter
port
If you give a port number to this function, the socket will be bound to this port locally before connecting anywhere. This is only useful for some silly protocols like FTP. The port can also be specified as a string, giving the name of the service associated with the port. Pass -1 to not specify a port (eg to bind only to an address).
- Parameter
address
You may specify an address to bind to if your machine has many IP numbers.
- Parameter
family_hint
A protocol family for the socket can be specified. If no family is specified, one which is appropriate for the address is automatically selected. Thus, there is normally no need to specify it. If you do not want to specify a bind address, you can provide the address as a hint here instead, to allow the automatic selection to work anyway.
- Returns
This function returns 1 for success, 0 otherwise.
- See also
connect()
,set_nonblocking()
,set_blocking()
- Methodopenat
File
openat(string(8bit)
filename
)File
openat(string(8bit)
filename
,string(7bit)
mode
)File
openat(string(8bit)
filename
,string(7bit)
mode
,int
mask
)- Description
Open a file relative to an open directory.
- See also
File.statat()
,File.unlinkat()
- Methodopenpt
int
openpt(string(7bit)
mode
)- Description
Open the master end of a pseudo-terminal pair. The parameter
mode
should contain one or more of the following letters:"r"
Open terminal for reading.
"w"
Open terminal for writing.
mode
should always contain at least one of the letters"r"
or"w"
.- See also
grantpt()
- Methodpipe
File
|zero
pipe(void
|int
required_properties
)- Description
This function creates a pipe between the object it was called in and an object that is returned.
- Parameter
required_properties
Binary or (
predef::`|()
) of requiredPROP_
properties.PROP_IPC
The resulting pipe may be used for inter process communication.
PROP_NONBLOCK
The resulting pipe supports nonblocking I/O.
PROP_SHUTDOWN
The resulting pipe supports shutting down transmission in either direction (see
close()
).PROP_BUFFERED
The resulting pipe is buffered (usually 4KB).
PROP_BIDIRECTIONAL
The resulting pipe is bi-directional.
PROP_SEND_FD
The resulting pipe might support sending of file descriptors (see
send_fd()
andreceive_fd()
for details).PROP_TTY
The resulting pipe is a pseudo-tty.
PROP_REVERSE
The resulting pipe supports communication "backwards" (but not necessarily "forwards", see
PROP_BIDIRECTIONAL
).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 (unlessPROP_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 (unlessPROP_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.
- Note
Calling this function with an argument of 0 is not the same as calling it with no arguments.
- See also
Process.create_process()
,send_fd()
,receive_fd()
,PROP_IPC
,PROP_NONBLOCK
,PROP_SEND_FD
,PROP_SHUTDOWN
,PROP_BUFFERED
,PROP_REVERSE
,PROP_BIDIRECTIONAL
,PROP_TTY
- Methodquery_buffer_mode
array
(Stdio.Buffer
|int(0)
) query_buffer_mode()- Description
Get the active input and output buffers that have been set with
set_buffer_mode()
(if any).- Returns
Returns an array with two elements:
Array Stdio.Buffer
0
The current input buffer.
Stdio.Buffer
1
The current output buffer.
- See also
set_buffer_mode()
- Methodquery_read_callback
Methodquery_write_callback
Methodquery_read_oob_callback
Methodquery_write_oob_callback
Methodquery_close_callback
Methodquery_callbacks 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()- Description
These functions return the currently installed callbacks for the respective events.
query_callbacks
returns the callbacks in the same order asset_callbacks
andset_nonblocking
expect them.- See also
set_nonblocking()
,set_read_callback
,set_write_callback
,set_read_oob_callback
,set_write_oob_callback
,set_close_callback
,set_callbacks
- Methodquery_id
mixed
query_id()- Description
This function returns the id that has been set with
set_id()
.- See also
set_id()
- Methodread
string(8bit)
|zero
read(int
|void
nbytes
,bool
|void
not_all
)- Description
Read (optionally buffered) data from a file or a stream.
Proxy function for
Fd::read()
, that adds support for the buffering configured byset_buffer_mode()
- See also
read_function()
,write()
,Fd::read()
- Methodread_function
function
(:string(8bit)
|zero
) read_function(int
nbytes
)- Description
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 toString.SplitIterator
.
- Methodset_blocking
void
set_blocking()- Description
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.
- Note
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.- See also
set_nonblocking()
,set_nonblocking_keep_callbacks()
,set_blocking_keep_callbacks()
- Methodset_nonblocking_keep_callbacks
Methodset_blocking_keep_callbacks void
set_nonblocking_keep_callbacks()void
set_blocking_keep_callbacks()- Description
Toggle between blocking and nonblocking, without changing the callbacks.
- See also
set_nonblocking()
,set_blocking()
- Methodset_buffer_mode
void
set_buffer_mode(Stdio.Buffer
|int(0)
in
,Stdio.Buffer
|int(0)
out
)- Description
Toggle the file to Buffer mode.
In this mode reading and writing will be done via Buffer objects, in the directions you included buffers.
- Parameter
in
Input buffer. If this buffer is non-empty, its contents will be returned after any already received data.
- Parameter
out
Output buffer. If this buffer is non-empty, its contents will be sent after any data already queued for sending.
- Note
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.
- See also
query_buffer_mode()
- Methodset_callbacks
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
)- Description
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 toset_nonblocking
, this function does not do anything with the stream, and it doesn't even have to be open.- See also
set_read_callback
,set_write_callback
,set_read_oob_callback
,set_write_oob_callback
,set_close_callback
,query_callbacks
- Methodset_read_callback
Methodset_write_callback
Methodset_read_oob_callback
Methodset_write_oob_callback
Methodset_close_callback
Methodset_fs_event_callback 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
)- Description
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 backendPike.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 callclose_cb
, then this callback (unlessclose_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, thenwrite_cb
will be tried. This also means thatwrite_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 likequery_address
, and the underlying file descriptor is still allocated). Also, this callback will not be called for a local close, neither by a call toclose
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 bywrite_cb
(or possiblywrite_oob_cb
).Events to
read_cb
andclose_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
andconnect
), a connection failure will callclose_cb
, and a successful connect will call eitherread_cb
orwrite_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.- Parameter
event_mask
An event mask specifing bitwise OR of one or more event types to monitor, selected from
Stdio.NOTE_WRITE
and friends.- Note
These functions do not set the file nonblocking.
- Note
Callbacks are also set by
set_callbacks
andset_nonblocking()
.- Note
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 withwrite
, and thewrite_oob_cb
callback is likewise disabled until something has been written withwrite_oob
. Since the data already has been read when the read callbacks are called, this effect is not noticeable for them.- Note
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.
- Note
Callback mode has nothing to do with nonblocking mode - although the two often are used together they don't have to be.
- Note
The file object will stay referenced from the backend object as long as there are callbacks that can receive events.
- Bugs
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.
- Note
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.
- See also
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
- Methodset_id
void
set_id(mixed
id
)- Description
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.- See also
query_id()
- Methodset_nonblocking
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()- Description
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.- Note
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.
- Note
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'.
- See also
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()
Class Stdio.FILE
- Annotations
@
Pike.Annotations.Implements
(NonblockingStream
)- Description
Stdio.FILE
is a buffered version ofStdio.File
, it inheritsStdio.File
and has most of the functionality ofStdio.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()
).- Note
The output part of
Stdio.FILE
is currently not buffered.
- Method_get_iterator
Stdio.FILEa;
foreach( a; index; value ) orprotected
object
_get_iterator()- Description
Returns an iterator that will loop over the lines in this file.
- See also
line_iterator()
- Methodgetchar
local
int
getchar()- Description
This function returns one character from the input stream.
- Returns
Returns the ISO-10646 (Unicode) value of the character.
- Note
Returns an
int
and not astring
of length 1.
- Methodgets
string
|zero
gets(bool
|void
not_all
)- Description
Read one line of input with support for input conversion.
- Parameter
not_all
Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.
- Returns
This function returns the line read if successful, and
0
if no more lines are available.- See also
ngets()
,read()
,line_iterator()
,set_charset()
- Methodline_iterator
String.SplitIterator
|LineIterator
line_iterator(int
|void
trim
)- Description
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.- Note
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 toread
,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.- See also
_get_iterator()
- Methodngets
array
(string
)|zero
ngets(void
|int(1..)
n
,bool
|void
not_all
)- Description
Get
n
lines.- Parameter
n
Number of lines to get, or all remaining if zero.
- Parameter
not_all
Set this parameter to ignore partial lines at EOF. This is useful for eg monitoring a growing logfile.
- Methodopenat
FILE
openat(string(8bit)
filename
)FILE
openat(string(8bit)
filename
,string(7bit)
mode
)FILE
openat(string(8bit)
filename
,string(7bit)
mode
,int
mask
)- Description
Same as
Stdio.File()->openat()
, but returns anStdio.FILE
object.- See also
Stdio.File()->openat()
- Methodpipe
FILE
pipe(void
|int
flags
)- Description
Same as
Stdio.File()->pipe()
, but returns anStdio.FILE
object.- See also
Stdio.File()->pipe()
- Methodprintf
int
printf(string
format
,mixed
...data
)- Description
This function does approximately the same as:
.write
(sprintf
(format
,@data
))- See also
write()
,sprintf()
- Methodread
string
read(int
|void
bytes
,void
|bool
now
)- Description
Read
bytes
(wide-) characters with buffering and support for input conversion.- See also
Stdio.File()->read()
,set_charset()
,unread()
- Methodset_charset
void
set_charset(string(8bit)
|void
charset
)- Description
Sets the input and output charset of this file to the specified
charset
. Ifcharset
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".
- FIXME
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.
- Methodungets
void
ungets(string
s
)- Description
This function puts a line back in the input buffer. The line can then be read with eg
read()
,gets()
orgetchar()
.- Note
The string is autoterminated by an extra line-feed.
- See also
read()
,gets()
,getchar()
,unread()
- Methodunread
void
unread(string
s
)- Description
This function puts a string back in the input buffer. The string can then be read with eg
read()
,gets()
orgetchar()
.- See also
read()
,gets()
,getchar()
,ungets()
9.6. Ports and UDP
Class Stdio.Port
- Description
Handles listening to socket ports. Whenever you need a bound socket that is open and listens for connections you should use this program.
- Methodaccept
File
|zero
accept()- Description
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.- See also
Stdio.File
,fd_factory()
- Methodcreate
Stdio.PortStdio.Port()
Stdio.PortStdio.Port(
int
|string
port
)Stdio.PortStdio.Port(
int
|string
port
,function
(:void
)accept_callback
)Stdio.PortStdio.Port(
int
|string
port
,function
(:void
)accept_callback
,string
ip
)Stdio.PortStdio.Port(
"stdin"
)Stdio.PortStdio.Port(
"stdin"
,function
(:void
)accept_callback
)- Description
If the first argument is other than
"stdin"
the arguments will be passed tobind()
.When create is called with
"stdin"
as the first argument, a socket is created out of the file descriptor0
. This is only useful if it actually is a socket to begin with, and is equivalent to creating a port and initializing it withlisten_fd
(0).- See also
bind
Class Stdio.UDP
- Description
UDP (User Datagram Protocol) handling.
- Methodset_nonblocking
UDP
set_nonblocking()UDP
set_nonblocking(void
|function
(mapping
(string
:int
|string
),mixed
... :void
)read_cb
,mixed
...extra_args
)- Description
Set this object to nonblocking mode.
If
read_cb
andextra_args
are specified, they will be passed on toset_read_callback()
.- Returns
The called object.
- Methodset_read_callback
UDP
set_read_callback(function
(mapping
(string
:int
|string
),mixed
... :void
)|zero
read_cb
,mixed
...extra_args
)- Description
The
read_cb
function will receive a mapping similar to the mapping returned byread()
:"data"
:string
Received data.
"ip"
:string
Data was sent from this IP.
"port"
:int
Data was sent from this port.
- Returns
The called object.
- See also
read()
9.7. Terminal I/O
Module Stdio.Terminfo
- MethodgetFallbackTerm
protected
Termcap
getFallbackTerm(string
term
)- Description
Returns an object describing the fallback terminal for the terminal
term
. This is usually equivalent toStdio.Terminfo.getTerm("dumb")
.- See also
Stdio.Terminfo.getTerm
- MethodgetTerm
Termcap
getTerm(string
|void
term
)- Description
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.
- See also
Stdio.Terminfo.getTerminfo, Stdio.Terminfo.getTermcap, Stdio.getFallbackTerm
- MethodgetTermcap
Termcap
getTermcap(string
term
)- Description
Returns the terminal description object for
term
from the systems termcap database. Returns 0 if not found.- See also
Stdio.Terminfo.getTerm, Stdio.Terminfo.getTerminfo
- MethodgetTerminfo
Terminfo
getTerminfo(string
term
)- Description
Returns the terminal description object for
term
from the systems terminfo database. Returns 0 if not found.- See also
Stdio.Terminfo.getTerm, Stdio.Terminfo.getTermcap
- Methodis_tty
int
is_tty()- Description
Returns 1 if
Stdio.stdin
is connected to an interactive terminal that can handle backspacing, carriage return without linefeed, and the like.
Class Stdio.Terminfo.MetaTerminfoDB
- Description
TerminfoDB
that merges several directorys.
- Methodcreate
Stdio.Terminfo.MetaTerminfoDBStdio.Terminfo.MetaTerminfoDB(
array
(TerminfoDB
|string
)|void
dbs
)- Description
Create a new Meta
TerminfoDB
.- Parameter
dbs
Array with elements in priority order. Elements may be either
TerminfoDB
An active
TerminfoDB
.string
A directory that may exist and contain a terminfo database.
- Returns
If the resulting set of
TerminfoDB
's is empty, the object will be destructed.
Class Stdio.Terminfo.Termcap
- Description
Termcap terminal description object.
- Methodcreate
Stdio.Terminfo.TermcapStdio.Terminfo.Termcap(
string
cap
,TermcapDB
|void
tcdb
,int
|void
maxrecurse
)
Class Stdio.Terminfo.TermcapDB
- Description
Termcap database
Class Stdio.Terminfo.Terminfo
- Description
Terminfo terminal description object
Class Stdio.Terminfo.TerminfoDB
- Description
Terminfo database for a single directory.
- MethodgetFallbackTerm
Class Stdio.Readline
- Description
Terminal-aware line-based input.
- Example
// 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());
- See also
enable_history()
,get_history()
,get_input_controller()
,message()
,read()
,set_prompt()
- Methodcreate
Stdio.ReadlineStdio.Readline(
object
|void
infd
,object
|string
|void
interm
,object
|void
outfd
,object
|string
|void
outterm
)- Description
Creates a Readline object, that takes input from
infd
and has output onoutfd
.- Parameter
infd
Defaults to
Stdio.stdin
.- Parameter
interm
Defaults to
Stdio.Terminfo.getTerm()
.- Parameter
outfd
Defaults to
infd
, unlessinfd
is 0, in which caseoutfd
defaults toStdio.stdout
.- Parameter
outterm
Defaults to
interm
.
- Methoddelta_history
void
delta_history(int
d
)- Description
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).- Note
Only effective if you have a history object.
- Methodedit
string
|zero
edit(string
data
,string
|void
local_prompt
,array
(string
)|void
attrs
)- Description
Read a line of data from the input.
- Parameter
data
Initial/default value that the user may edit.
- Parameter
local_prompt
Alternative prompt. Defaults to the prompt set by
set_prompt()
.- Parameter
attrs
Alternative prompt attributes. Defaults to the attributes set by
set_prompt()
.- See also
read()
- Methodenable_history
void
enable_history(array
(string
)|History
|int
hist
)- Description
Enable/disable history.
- Parameter
hist
zero
Disable history.
int(1..)
Enable history of max
hist
lines. If history is already enabled it is kept and the maximum number of lines adjusted.array
(string
)Set the history to this array of lines. The maximum number of lines is set to 512.
History
Use this
History
object.
- Methodget_input_controller
InputController
get_input_controller()- Description
get current input control object
- Returns
Terminal input controller object
- Methodget_output_controller
OutputController
get_output_controller()- Description
get current output control object
- Returns
Terminal output controller object
- Methodread
string
read(string
|void
prompt
,array
(string
)|void
attrs
)- Description
Read a line of data from the input.
- Parameter
prompt
Alternative prompt. Defaults to the prompt set by
set_prompt()
.- Parameter
attrs
Alternative prompt attributes. Defaults to the attributes set by
set_prompt()
.This function is essentially a short hand for
edit("", prompt, attrs)
.- See also
edit()
- Methodset_blocking
void
set_blocking()- Description
Disable nonblocking mode.
This is equivalent to calling
set_nonblocking(0)
.- See also
set_nonblocking()
- Methodset_echo
void
set_echo(int
onoff
)- Description
Set text echo on or off.
- Parameter
onoff
1 for echo, 0 for no echo.
- Methodset_nonblocking
void
set_nonblocking(function
(string
|zero
:void
)|zero
f
)- Description
Set a function to be called every time a line is completed.
- Parameter
f
Function to call when a line is completed, or
0
(zero) to disable. It will be called with a string when a line is completed, and0
(zero) wheneof()
is called.- See also
set_blocking()
,read()
- Methodset_prompt
string
set_prompt(string
newp
,array
(string
)|void
newattrs
)- Description
Set the prompt string.
- Parameter
newp
New prompt string
- Parameter
newattrs
Terminal attributes
- Methodwrite
void
write(string
msg
,void
|int
word_wrap
)- Description
Print a message to the output device with optional word wrap.
- See also
message()
Class Stdio.Readline.DefaultEditKeys
Class Stdio.Readline.History
- Methodpop
bool
pop(string
|void
text
)- Description
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.
- Methodpop
Class Stdio.Readline.InputController
- FIXME
Ought to have support for charset conversion.
- Methodcreate
Stdio.Readline.InputControllerStdio.Readline.InputController(
object
|void
_infd
,object
|string
|void
_term
)
Class Stdio.Readline.OutputController
- FIXME
Ought to have support for charset conversion.
- Methodcheck_columns
int
check_columns()- Description
Check and return the terminal width.
- Note
In Pike 7.4 and earlier this function returned
void
.- See also
get_number_of_columns
- Methodcreate
Stdio.Readline.OutputControllerStdio.Readline.OutputController(
.File
|void
_outfd
,.Terminfo.Termcap
|string
|void
_term
)
- Methodget_number_of_columns
int
get_number_of_columns()- Description
Returns the width of the terminal.
- Note
Does not check the width of the terminal.
- See also
check_columns
9.8. Other
Module Stdio
- Typedefclose_callback_t
local
typedeffunction
(mixed
|void
:int
)|zero
Stdio.close_callback_t
- Description
The type for close callback functions.
- Typedeffs_event_callback_t
local
typedeffunction
(mixed
|void
,int
:int
)|zero
Stdio.fs_event_callback_t
- Description
The type for fs_event callback function functions.
- Typedefread_callback_t
local
typedeffunction
(mixed
|void
,string
:int
|void
)|function
(mixed
|void
,Buffer
:int
|void
)|function
(mixed
|void
:int
|void
)|zero
Stdio.read_callback_t
- Description
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 aBuffer
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.
- Typedefread_oob_callback_t
local
typedeffunction
(mixed
|void
,string
|void
:int
)|zero
Stdio.read_oob_callback_t
- Description
The type for read out of band callback functions.
- Typedefwrite_callback_t
local
typedeffunction
(mixed
|void
:int
|void
)|function
(mixed
|void
,Buffer
:int
|void
)|zero
Stdio.write_callback_t
- Description
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 aBuffer
has been enabled for writing, add data to that buffer to send it.
- Typedefwrite_oob_callback_t
local
typedeffunction
(mixed
|void
:int
)|zero
Stdio.write_oob_callback_t
- Description
The type for write out of band callback functions.
- ConstantDATA_CHUNK_SIZE
final
constantint
Stdio.DATA_CHUNK_SIZE
- Description
Size used in various places to divide incoming or outgoing data into chunks.
- ConstantTCSADRAIN
constant
string
Stdio.TCSADRAIN
- Description
Argument to
Stdio.File()->tcsetattr()
.Change after all output has been written.
- ConstantTCSAFLUSH
constant
string
Stdio.TCSAFLUSH
- Description
Argument to
Stdio.File()->tcsetattr()
.Change after all output has been written, and empty the input buffers.
- ConstantTCSANOW
constant
string
Stdio.TCSANOW
- Description
Argument to
Stdio.File()->tcsetattr()
.Change immediately.
- Variablestderr
FILE
Stdio.stderr- Description
An instance of FILE("stderr"), the standard error stream. Use this when you want to output error messages.
- See also
predef::werror()
- Variablestdin
FILE
Stdio.stdin- Description
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 justwrite()
, since they are the same function.- Example
int main() { int line; while(string s=Stdio.stdin.gets()) write("%5d: %s\n", line++, s); }
- Variablestdout
FILE
Stdio.stdout- Description
An instance of FILE("stdout"), the standatd output stream. Use this when you want to write anything to the standard output.
- See also
predef::write()
- Methodappend_file
int
append_file(string
filename
,string
str
,int
|void
access
)- Description
Append the string
str
onto the filefilename
.For a description of
access
, seeStdio.File->open()
.- Throws
Throws an error if
filename
couldn't be opened for writing.- Returns
Returns the number of bytes written, i.e.
sizeof(str)
.- See also
write_file()
,read_bytes()
,Stdio.File()->open()
- Methodappend_path
Methodappend_path_unix
Methodappend_path_nt string
append_path(string
absolute
,string
...relative
)string
append_path_unix(string
absolute
,string
...relative
)string
append_path_nt(string
absolute
,string
...relative
)- Description
Append
relative
paths to anabsolute
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 inrelative
by removing the colon separator":"
if it exists (k:/fnord appends as k/fnord)append_path_nt()
also makes sure that UNC path(s) inrelative
is appended correctly by removing any"\\"
or"//"
from the beginning.append_path()
is equivalent toappend_path_unix()
on UNIX-like operating systems, and equivalent toappend_path_nt()
on NT-like operating systems.- See also
combine_path()
- Methodasync_cp
void
async_cp(string
from
,string
to
,function
(int
,mixed
... :void
)callback
,mixed
...args
)- Description
Copy a file asynchronously.
This function is similar to
cp()
, but works asynchronously.- Parameter
from
Name of file to copy.
- Parameter
to
Name of file to create or replace with a copy of
from
.- Parameter
callback
Function to be called on completion. The first argument will be
1
on success, and0
(zero) otherwise. The rest of the arguments tocallback
are passed verbatim fromargs
.- Parameter
args
Extra arguments to pass to
callback
.- Note
For
callback
to be called, the backend must be active (iemain()
must have returned-1
, orPike.DefaultBackend
get called in some other way). The actual copying may start before the backend has activated.- Bugs
Currently the file sizes are not compared, so the destination file (
to
) may be truncated.- See also
cp()
,sendfile()
- Methodconvert_modestring2int
int
convert_modestring2int(string(7bit)
mode_string
)- Description
Convert the mode_string string as returned by Stdio.Stat object to int suitable for chmod
- Parameter
mode_string
The string as return from Stdio.Stat()->mode_string
- Returns
An int matching the permission of the mode_string string suitable for chmod
- Methodcp
int
cp(string
from
,string
to
)- Description
Copies the file
from
to the new positionto
. If there is no system function for cp, a new file will be created and the old one copied manually in chunks ofDATA_CHUNK_SIZE
bytes.This function can also copy directories recursively.
- Returns
0 on error, 1 on success
- Note
This function keeps file and directory mode bits, unlike in Pike 7.6 and earlier.
- Methodexist
int
exist(string(8bit)
path
)- Description
Check if a
path
exists.- Returns
Returns true if the given path exists (is a directory or file), otherwise false.
- Note
May fail with eg
errno()
EFBIG if the file exists, but the filesystem doesn't support the file size.- See also
is_dir()
,is_file()
,is_link()
,file_stat()
- Methodfile_equal
int
file_equal(string
file_1
,string
file_2
)- Description
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.
- Methodfile_size
int
file_size(string
filename
)- Description
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.
- See also
file_stat()
,write_file()
,read_bytes()
- Methodis_dir
int
is_dir(string
path
)- Description
Check if a
path
is a directory.- Returns
Returns true if the given path is a directory, otherwise false.
- See also
exist()
,is_file()
,is_link()
,file_stat()
- Methodis_file
int
is_file(string
path
)- Description
Check if a
path
is a file.- Returns
Returns true if the given path is a regular file, otherwise false.
- See also
exist()
,is_dir()
,is_link()
,file_stat()
- Methodis_link
int
is_link(string
path
)- Description
Check if a
path
is a symbolic link.- Returns
Returns true if the given path is a symbolic link, otherwise false.
- See also
exist()
,is_dir()
,is_file()
,file_stat()
- Methodmkdirhier
int
mkdirhier(string
pathname
,void
|int
mode
)- Description
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
Returns zero on failure and nonzero on success.
- See also
mkdir()
- Methodperror
void
perror(string
s
)- Description
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.
- See also
werror()
- Methodread_bytes
string
read_bytes(string
filename
,int
start
,int
len
)string
read_bytes(string
filename
,int
start
)string
read_bytes(string
filename
)- Description
Read
len
number of bytes from a regular filefilename
starting at bytestart
, 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
Throws an error on any I/O error except when the file doesn't exist.
- Returns
Returns
0
(zero) if the file doesn't exist or ifstart
is beyond the end of it.Returns a string with the requested data otherwise.
- See also
read_file
,write_file()
,append_file()
- Methodread_file
string
read_file(string
filename
)string
read_file(string
filename
,int
start
,int
len
)- Description
Read
len
lines from a regular filefilename
after skippingstart
lines and return those lines as a string. If bothstart
andlen
are omitted the whole file is read.- Throws
Throws an error on any I/O error except when the file doesn't exist.
- Returns
Returns
0
(zero) if the file doesn't exist or ifstart
is beyond the end of it.Returns a string with the requested data otherwise.
- See also
read_bytes()
,write_file()
- Methodrecursive_mv
int
recursive_mv(string
from
,string
to
)- Description
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
Returns 0 on failure, nonzero otherwise.
- See also
recursive_rm
cp
- Methodrecursive_rm
int
recursive_rm(string
path
)- Description
Remove a file or a directory tree.
- Returns
Returns 0 on failure, nonzero otherwise.
- See also
rm
- Methodsendfile
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
)- Description
Sends
headers
followed bylen
bytes starting atoffset
from the filefrom
followed bytrailers
to the fileto
. When completedcallback
will be called with the total number of bytes sent as the first argument, followed byargs
.Any of
headers
,from
andtrailers
may be left out by setting them to0
.Setting
offset
to-1
means send from the current position infrom
.Setting
len
to-1
means send untilfrom
's end of file is reached.- Note
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 (iemain()
must have returned-1
, orPike.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 wantfrom
to have the same backend asto
.- Note
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.- Bugs
FIXME: Support for timeouts?
- See also
Stdio.File->set_nonblocking()
- Methodsimplify_path
string
simplify_path(string
path
)- Description
Returns a canonic representation of
path
(without /./, /../, // and similar path segments).
- Methodwerror
void
werror(string
s
)- Description
Write a message to stderr. Stderr is normally the console, even if the process output has been redirected to a file or pipe.
- Note
This function is identical to
predef::werror()
.- See also
predef::werror()
- Methodwrite_file
int
write_file(string
filename
,string
str
,int
|void
access
)- Description
Write the string
str
onto the filefilename
. Any existing data in the file is overwritten.For a description of
access
, seeStdio.File()->open()
.- Throws
Throws an error if
filename
couldn't be opened for writing.- Returns
Returns the number of bytes written, i.e.
sizeof(str)
.- See also
append_file()
,read_bytes()
,Stdio.File()->open()
Class Stdio.BlockFile (< StringType >)
- Annotations
@
Pike.Annotations.Implements
(InputBlockFile
)@
Pike.Annotations.Implements
(Stream
)- Description
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.- See also
Stream
,NonblockingStream
,InputBlockStream
,File
,FILE
Class Stdio.FakeFile
- Annotations
@
Pike.Annotations.Implements
(Stdio.BlockFile
)@
Pike.Annotations.Implements
(Stdio.NonblockingStream
)- Description
A string wrapper that pretends to be a
Stdio.File
object in addition to some features of aStdio.FILE
object.
- Constantis_fake_file
constant
int
Stdio.FakeFile.is_fake_file
- Description
This constant can be used to distinguish a FakeFile object from a real
Stdio.File
object.
- Method_sizeof
int(0..)
sizeof(Stdio.FakeFilearg)- Description
Sizeof on a FakeFile returns the size of its contents.
- Methodcast
(int)Stdio.FakeFile()
(float)Stdio.FakeFile()
(string)Stdio.FakeFile()
(array)Stdio.FakeFile()
(mapping)Stdio.FakeFile()
(multiset)Stdio.FakeFile()- Description
A FakeFile can be casted to a string.
- Methodcreate
Stdio.FakeFileStdio.FakeFile(
string
data
,void
|string
type
,void
|int
pointer
)- See also
Stdio.File()->create()
- Methodline_iterator
String.SplitIterator
line_iterator(int
|void
trim
)- See also
Stdio.File()->line_iterator()
- Methodquery_address
string
|zero
query_address(void
|bool
is_local
)- Description
Always returns 0.
- See also
Stdio.File()->query_address()
- Methodquery_close_callback
function
(:void
)|zero
query_close_callback()- See also
Stdio.File()->query_close_callback
- Methodquery_read_callback
function
(:void
)|zero
query_read_callback()- See also
Stdio.File()->query_read_callback
- Methodquery_read_oob_callback
function
(:void
)|zero
query_read_oob_callback()- See also
Stdio.File()->query_read_oob_callback
- Methodquery_write_callback
function
(:void
)|zero
query_write_callback()- See also
Stdio.File()->query_write_callback
- Methodquery_write_oob_callback
function
(:void
)|zero
query_write_oob_callback()- See also
Stdio.File()->query_write_oob_callback
- Methodset_blocking_keep_callbacks
void
set_blocking_keep_callbacks()- See also
Stdio.File()->set_blocking_keep_callbacks
- Methodset_close_callback
void
set_close_callback(Stdio.close_callback_t
cb
)- See also
Stdio.File()->set_close_callback
- Methodset_nonblocking
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
)- See also
Stdio.File()->set_blocking
- Methodset_nonblocking_keep_callbacks
void
set_nonblocking_keep_callbacks()- See also
Stdio.File()->set_blocking_keep_callbacks
- Methodset_read_callback
void
set_read_callback(Stdio.read_callback_t
cb
)- See also
Stdio.File()->set_read_callback
- Methodset_read_oob_callback
void
set_read_oob_callback(Stdio.read_oob_callback_t
cb
)- See also
Stdio.File()->set_read_oob_callback
- Methodset_write_callback
void
set_write_callback(Stdio.write_callback_t
cb
)- See also
Stdio.File()->set_write_callback
- Methodset_write_oob_callback
void
set_write_oob_callback(Stdio.write_oob_callback_t
cb
)- See also
Stdio.File()->set_write_oob_callback
Class Stdio.FakePipe
- Description
This module emulates a bidirectional pipe/socket without using any actual file descriptors.
Class Stdio.FakePipe.InternalSocket
- Description
Class that implements one end of an emulated bi-directional pipe/socket.
- Variable_other
Variable_read_buffer
Variable_write_buffer
Variablemux
Variablecond protected
this_program
|zero
Stdio.FakePipe.InternalSocket._otherStdio.Buffer
|zero
Stdio.FakePipe.InternalSocket._read_bufferStdio.Buffer
|zero
Stdio.FakePipe.InternalSocket._write_bufferprotected
Thread.Mutex
Stdio.FakePipe.InternalSocket.muxprotected
Thread.Condition
Stdio.FakePipe.InternalSocket.cond
- Variableother
this_program
Stdio.FakePipe.InternalSocket.other- Description
The other end of the emulated pipe/socket.
- Note
Read only
- Method__create__
protected
local
void
__create__(this_program
|zero
_other
,Stdio.Buffer
|zero
_read_buffer
,Stdio.Buffer
|zero
_write_buffer
,Thread.Mutex
mux
,Thread.Condition
cond
)
- Methodcreate
Stdio.FakePipe.InternalSocketStdio.FakePipe.InternalSocket(
this_program
|zero
_other
,Stdio.Buffer
|zero
_read_buffer
,Stdio.Buffer
|zero
_write_buffer
,Thread.Mutex
mux
,Thread.Condition
cond
)
- Methodset_nonblocking
void
set_nonblocking(function
(:void
)rcb
,function
(:void
)wcb
,function
(:void
)ccb
)
Class Stdio.InputBlockFile (< StringType >)
- Annotations
@
Pike.Annotations.Implements
(InputStream
)- Description
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.- See also
InputStream
,NonblockingInputStream
,BlockFile
,File
,FILE
Class Stdio.InputStream (< StringType >)
- Description
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.
- See also
Stream
,NonblockingInputStream
,InputBlockFile
,File
,FILE
- Methodread_function
function
(:StringType
|zero
) read_function(int
nbytes
)- Description
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 toString.SplitIterator
.
Class Stdio.NonblockingInputStream (< StringType >)
- Annotations
@
Pike.Annotations.Implements
(InputStream
)- Description
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.- See also
InputStream
,NonblockingStream
,InputBlockFile
,File
,FILE
- Methodset_read_callback
Methodset_close_callback
Methodset_fs_event_callback 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
)
- Methodset_nonblocking
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
)
Class Stdio.NonblockingOutputStreamMixin (< StringType >)
- Description
Mixin for converting a
NonblockingInputStream
into aNonblockingStream
.This class exists purely for typing reasons.
- Note
Typically you will not want to use this class directly, but instead use one of the classes that inherits it.
- See also
NonblockingInputStream
,NonblockingStream
Class Stdio.NonblockingStream (< StringType >)
- Annotations
@
Pike.Annotations.Implements
(Stream
)- Description
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.- See also
Stream
,NonblockingInputStream
,BlockFile
,File
,FILE
- InheritNonblockingInputStream
inherit NonblockingInputStream(<
StringType
>) : NonblockingInputStream
Class Stdio.OutputStreamMixin (< StringType >)
- Description
Mixin for converting an
InputStream
into aStream
.This class exists purely for typing reasons.
- Note
Typically you will not want to use this class directly, but instead use one of the classes that inherits it.
- See also
InputStream
,Stream
,BlockFile
Class Stdio.Stream (< StringType >)
- Annotations
@
Pike.Annotations.Implements
(InputStream
)- Description
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.
- See also
InputStream
,NonblockingStream
,BlockFile
,File
,FILE
Class Stdio.sendfile
- Description
Send
headers + from_fd[off..off+len-1] + trailers
toto_fd
asyncronously.- Note
This is the low-level implementation, which has several limitations. You probably want to use
Stdio.sendfile()
instead.- See also
Stdio.sendfile()
- Methodcreate
Stdio.sendfileStdio.sendfile(
array
(string
)headers
,object
from
,int
offset
,int
len
,array
(string
)trailers
,object
to
,function
(:void
)callback
,mixed
...args
)- Description
Low-level implementation of
Stdio.sendfile()
.Sends
headers
followed bylen
bytes starting atoffset
from the filefrom
followed bytrailers
to the fileto
. When completedcallback
will be called with the total number of bytes sent as the first argument, followed byargs
.Any of
headers
,from
andtrailers
may be left out by setting them to0
.Setting
offset
to-1
means send from the current position infrom
.Setting
len
to-1
means send untilfrom
's end of file is reached.- Note
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 withto
.- Note
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.- See also
Stdio.sendfile()
Module Stdio.Pipe
Class Stdio.Pipe.Base
- Description
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.
- Methodcreate
Stdio.Pipe.BaseStdio.Pipe.Base(
Gz.deflate
|void
engine
)- Description
Note that the Gz.deflate engine provided needs to be preconfigured using negative compression levels.
- Methodset_nonblocking
final
void
set_nonblocking(function
(:void
)rcb
,function
(:void
)wcb
,function
(:void
)ccb
)
Class Stdio.Pipe.Gunzip
- Description
This module provides a gzip-uncompressing non-blocking pipe interface.
Class Stdio.Pipe.Gzip
- Description
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.
- Typedefclose_callback_t