Method _Stdio.Fd()->write()


Method write

int write(string(8bit) data)
int write(string(8bit) format, mixed ... extras)
int write(array(string(8bit)) data)
int write(array(string(8bit)) format, mixed ... extras)
int write(Stdio.Buffer|String.Buffer|System.Memory data, void|int(0..) offset)

Description

Write data to a file or a stream.

If there are any file descriptors that have been queued for sending (with send_fd()), they will be sent.

Parameter data

Data to write.

If data is an array of strings, they are written in sequence.

Parameter format
Parameter extras

If more than one argument is given, sprintf() is used to format them using format. If format is an array, the strings in it are concatenated and the result is used as format string.

Parameter offset

The offset in data to start writing from.

Returns

Writes data and returns the number of bytes that were actually written.

(1..)

The number of bytes successfully written to the OS buffers.

This can be less than the size of the given data if eg:

  • Some data was written successfully and then something went wrong.

    If only some data was written due to an error and that error persists, then a later call to write() will fail and return -1.

  • Nonblocking mode is used and not all data could be written without blocking.

0

No bytes were written. This may be due to

  • data or the formatted data being the empty string.

  • Nonblocking mode is used and no data could be written without blocking.

-1

Something went wrong and no bytes were written.

If everything went fine, a call to errno() directly afterwards returns zero.

Note

Writing of wide strings is not supported. You have to encode the data somehow, e.g. with string_to_utf8 or with one of the charsets supported by Charset.encoder.

Note

The variant of this function using a buffer object does not release the interpreter lock.

See also

read(), write_oob(), send_fd()