Home Contents | # rawio:write | Rawio | Core4 Lua Event System

## SYNOPSIS

handle:write(data [, data, ...])

## DESCRIPTION

Writes data to the open file.

For real files (as opposed to, e.g. devices or network connections), the file index is advanced by the number of files written. If the file was opened in append mode, the file index is moved to the end of the file before writing takes place.

In blocking mode, the call will not return until all data could be written or an error condition exists.

When in non-blocking mode, then the number of bytes written may be less than the length specified if there is insufficient space on the underlying physical medium (files) or if the transmit buffer is getting full (network sockets, serial devices, printers, etc...).

If multiple arguments are given, the contents of the variables are considered as one concatenated string. (This is more efficient than concatenating the strings with normal Lua mechanisms first.)

## RETURN VALUE

On success, returns the number of bytes written.

A return value of zero indicates an end-of-file condition. This is typically returned by a TCP network connection if the connection has been closed already.

On error, returns nil. In case of an error, the error can be retrieved using rawio:lastError()

Only in non-blocking mode, an error condition of error code EAGAIN returned by rawio:lastError() means that the call was not able to write anything, as the operating system buffers are full. This asks the application to please try again later. (It is possible to set up an event callback using event:add() for the POLLOUT event. That callback will run when the operating system is able to accept more data.)

## NOTES

Please note that Lua considers the number '0' true. Using
if (handle:write(...)) then print("OK") end
will happily print OK if zero bytes where written.

## EXAMPLE

> >
handle = rawio.attach(1) handle:write("Hello", " ", "World\n")
Hello World

## SEE ALSO

rawio.attach, rawio:blocking, rawio:canReadLine, rawio:clearError, rawio:close, rawio:connect, rawio:detach, rawio:lastError, rawio:line, rawio:lines, rawio.access, rawio.open, rawio:read, rawio:slurp, rawio:copy, rawio.stat, rawio.statfs, rawio:writet, rawio:writes