HomeSYNOPSIS
handle:writes(data, [ i, [ j, [ timeout ]]])
DESCRIPTION
Writes data to the open file.
The optional arguments i and j allow selecting a substring of data. When given, the call uses the substring of data that starts at i and continues until j; i and j can be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length).
The optional timeout value instructs the call to wait for at most the passed number of milliseconds for completion. When the timeout value is not given, behaviour depends on rawio:blocking() mode.
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...).
A successful return of this call indicates only that the data was passed on to the operating system. Typically, writes are buffered in the kernel and still take some unspecified amount of time to actually reach their destination.
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.
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.)
When the timeout has expired (if used) and some data could be written, the function returns the number of bytes that could be written. If no data could be written, it returns a failure with the error code ETIME.
NOTES
Please note that Lua considers the number '0' true. Using
if (handle:writes(...)) then print("OK") end
will happily print OK if zero bytes where written.