SIO_put
2-400
C Interface
Syntax
nmadus = SIO_put(stream, bufp, nmadus);
Parameters
SIO_Handle stream;
/* stream handle */
Ptr
*bufp;
/* pointer to a buffer */
size_t
nmadus; /* number of MADUs in the buffer */
Return Value
Int
nmadus; /* number of MADUs, negative if error */
Description
SIO_put exchanges a non-empty buffer with an empty buffer. The bufp
parameter is an input/output parameter that points to a non-empty buffer
when SIO_put is called. When SIO_put returns, bufp points to a new
(different) buffer, and nmadus indicates success or failure of the call.
SIO_put blocks until a buffer can be returned to the caller, or until the
stream's timeout attribute expires (see SIO_create). If a timeout occurs,
the value (-1 * SYS_ETIMEOUT) is returned. If timeout is not equal to
SYS_FOREVER or 0, the task suspension time can be up to 1 system
clock tick less than timeout due to granularity in system timekeeping.
To indicate success, SIO_put returns a positive value for nmadus. As a
success indicator, nmadus is the number of valid MADUs in the buffer
returned by the stream (usually zero). To indicate failure, SIO_put returns
a negative value (the actual error code multiplied by -1).
An inconsistency exists between the sizes of buffers in a stream and the
return types corresponding to these sizes. While all buffer sizes in a
stream are of type size_t, APIs that return a buffer size return a type of
Int. The inconsistency is due to a change in stream buffer sizes and the
need to retain the return type for backward compatibility. Because of this
inconsistency, it is not possible to return the correct buffer size when the
actual buffer size exceeds the size of an Int type. This issue has the
following implications:
❏
If the actual buffer size is less than/equal to the maximum
positive Int value (15 bits).
Check the return value for negative
values, which should be treated as errors. Positive values reflect the
correct size.
❏
If the actual buffer size is greater than the maximum positive Int
value.
Ignore the return value. There is little room for this situation on
’C55x large model since size_t is the same as unsigned int. Since the
sign in Int takes up one bit, the size_t type contains just one more bit
than an Int. If you are using the ’C55x huge model, size_t is 32 bits
and Int allows positive integers only up to 15 bits.
SIO_put
Put a buffer to a stream
