12.3.108 user_write()

Synopsis

spio_t_error_code
user_write(
  void *user_data,
  void const *buf,
  size_t *pbuf_size,
  spio_t_bits write_options
  );

This is the prototype for one of the methods of user defined streams. It is used when SICStus wants to write data to the user defined stream.

Arguments

user_data

The same value as was passed to SP_create_stream().

buf

Points to a buffer allocated by the caller containing the data to be written.

pbuf_size

Points to the size of the buffer, always positive. When this function returns successfully, *pbuf_size should be set to the number of bytes actually written, which should always be positive for successful return.

Note that buffer size is measured in bytes also for text streams.

write_options

The following bits can be set:

SPIO_DEVICE_WRITE_OPTION_BINARY

This is always specified if the device was created as a binary device. The buffer contains *pbuf_size bytes.

SPIO_DEVICE_WRITE_OPTION_TEXT

This is always specified if the device was created as a text device. The buffer contains wide characters, i.e. spio_t_wchar. Note that *buf_size is size in bytes, not in characters.

SPIO_DEVICE_WRITE_OPTION_NONBLOCKING

If this is set, the function should return quickly, either with some data written or with a SPIO_E_WOULD_BLOCK code.

If your user_write will never block, you can ignore this value.

You should return SPIO_E_NOT_SUPPORTED if user_write cannot support non-blocking write.

Return Value

On success, *pbuf_size should be assigned to with the number of bytes written and SPIO_S_NOERR or some other success code returned. On success, something must have been written, e.g. *pbuf_size must be set to a positive value.

On failure, return a SPIO error code. Error codes with special meaning for user_write:

SPIO_E_END_OF_FILE

Returned if it is not possible to write more data onto the stream, e.g. some underlying device has been closed.

SPIO_E_WOULD_BLOCK

SPIO_DEVICE_WRITE_OPTION_NONBLOCKING was set but the operation would block.

SPIO_E_NOT_SUPPORTED

Some unsupported option, e.g. SPIO_DEVICE_WRITE_OPTION_NONBLOCKING, was passed.

Other error codes may also be returned.

Description

Should write up to *buf_size bytes of data from buf. Data could be either bytes, for a binary device, or wide characters, for a text device.

See Also

cpg-ref-SP_create_stream. Defining a New Stream.