libserialport  unreleased development snapshot
cross-platform library for accessing serial ports
Functions
Data handling

Reading, writing, and flushing data. More...

Functions

enum sp_return sp_blocking_read (struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms)
 Read bytes from the specified serial port, blocking until complete. More...
 
enum sp_return sp_blocking_read_next (struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms)
 Read bytes from the specified serial port, returning as soon as any data is available. More...
 
enum sp_return sp_nonblocking_read (struct sp_port *port, void *buf, size_t count)
 Read bytes from the specified serial port, without blocking. More...
 
enum sp_return sp_blocking_write (struct sp_port *port, const void *buf, size_t count, unsigned int timeout_ms)
 Write bytes to the specified serial port, blocking until complete. More...
 
enum sp_return sp_nonblocking_write (struct sp_port *port, const void *buf, size_t count)
 Write bytes to the specified serial port, without blocking. More...
 
enum sp_return sp_input_waiting (struct sp_port *port)
 Gets the number of bytes waiting in the input buffer. More...
 
enum sp_return sp_output_waiting (struct sp_port *port)
 Gets the number of bytes waiting in the output buffer. More...
 
enum sp_return sp_flush (struct sp_port *port, enum sp_buffer buffers)
 Flush serial port buffers. More...
 
enum sp_return sp_drain (struct sp_port *port)
 Wait for buffered data to be transmitted. More...
 

Detailed Description

Reading, writing, and flushing data.

See send_receive.c for an example of sending and receiving data.

Function Documentation

enum sp_return sp_blocking_read ( struct sp_port port,
void *  buf,
size_t  count,
unsigned int  timeout_ms 
)

Read bytes from the specified serial port, blocking until complete.

Warning
If your program runs on Unix, defines its own signal handlers, and needs to abort blocking reads when these are called, then you should not use this function. It repeats system calls that return with EINTR. To be able to abort a read from a signal handler, you should implement your own blocking read using sp_nonblocking_read() together with a blocking method that makes sense for your program. E.g. you can obtain the file descriptor for an open port using sp_get_port_handle() and use this to call select() or pselect(), with appropriate arrangements to return if a signal is received.
Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]bufBuffer in which to store the bytes read. Must not be NULL.
[in]countRequested number of bytes to read.
[in]timeout_msTimeout in milliseconds, or zero to wait indefinitely.
Returns
The number of bytes read on success, or a negative error code. If the number of bytes returned is less than that requested, the timeout was reached before the requested number of bytes was available. If timeout is zero, the function will always return either the requested number of bytes or a negative error code.
Since
0.1.0
Examples:
send_receive.c.
enum sp_return sp_blocking_read_next ( struct sp_port port,
void *  buf,
size_t  count,
unsigned int  timeout_ms 
)

Read bytes from the specified serial port, returning as soon as any data is available.

Warning
If your program runs on Unix, defines its own signal handlers, and needs to abort blocking reads when these are called, then you should not use this function. It repeats system calls that return with EINTR. To be able to abort a read from a signal handler, you should implement your own blocking read using sp_nonblocking_read() together with a blocking method that makes sense for your program. E.g. you can obtain the file descriptor for an open port using sp_get_port_handle() and use this to call select() or pselect(), with appropriate arrangements to return if a signal is received.
Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]bufBuffer in which to store the bytes read. Must not be NULL.
[in]countMaximum number of bytes to read. Must not be zero.
[in]timeout_msTimeout in milliseconds, or zero to wait indefinitely.
Returns
The number of bytes read on success, or a negative error code. If the result is zero, the timeout was reached before any bytes were available. If timeout_ms is zero, the function will always return either at least one byte, or a negative error code.
Since
0.1.1
enum sp_return sp_blocking_write ( struct sp_port port,
const void *  buf,
size_t  count,
unsigned int  timeout_ms 
)

Write bytes to the specified serial port, blocking until complete.

Note that this function only ensures that the accepted bytes have been written to the OS; they may be held in driver or hardware buffers and not yet physically transmitted. To check whether all written bytes have actually been transmitted, use the sp_output_waiting() function. To wait until all written bytes have actually been transmitted, use the sp_drain() function.

Warning
If your program runs on Unix, defines its own signal handlers, and needs to abort blocking writes when these are called, then you should not use this function. It repeats system calls that return with EINTR. To be able to abort a write from a signal handler, you should implement your own blocking write using sp_nonblocking_write() together with a blocking method that makes sense for your program. E.g. you can obtain the file descriptor for an open port using sp_get_port_handle() and use this to call select() or pselect(), with appropriate arrangements to return if a signal is received.
Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]bufBuffer containing the bytes to write. Must not be NULL.
[in]countRequested number of bytes to write.
[in]timeout_msTimeout in milliseconds, or zero to wait indefinitely.
Returns
The number of bytes written on success, or a negative error code. If the number of bytes returned is less than that requested, the timeout was reached before the requested number of bytes was written. If timeout is zero, the function will always return either the requested number of bytes or a negative error code. In the event of an error there is no way to determine how many bytes were sent before the error occurred.
Since
0.1.0
Examples:
send_receive.c.
enum sp_return sp_drain ( struct sp_port port)

Wait for buffered data to be transmitted.

Warning
If your program runs on Unix, defines its own signal handlers, and needs to abort draining the output buffer when when these are called, then you should not use this function. It repeats system calls that return with EINTR. To be able to abort a drain from a signal handler, you would need to implement your own blocking drain by polling the result of sp_output_waiting().
Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_flush ( struct sp_port port,
enum sp_buffer  buffers 
)

Flush serial port buffers.

Data in the selected buffer(s) is discarded.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]buffersWhich buffer(s) to flush.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_input_waiting ( struct sp_port port)

Gets the number of bytes waiting in the input buffer.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
Number of bytes waiting on success, a negative error code otherwise.
Since
0.1.0
Examples:
await_events.c.
enum sp_return sp_nonblocking_read ( struct sp_port port,
void *  buf,
size_t  count 
)

Read bytes from the specified serial port, without blocking.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]bufBuffer in which to store the bytes read. Must not be NULL.
[in]countMaximum number of bytes to read.
Returns
The number of bytes read on success, or a negative error code. The number of bytes returned may be any number from zero to the maximum that was requested.
Since
0.1.0
enum sp_return sp_nonblocking_write ( struct sp_port port,
const void *  buf,
size_t  count 
)

Write bytes to the specified serial port, without blocking.

Note that this function only ensures that the accepted bytes have been written to the OS; they may be held in driver or hardware buffers and not yet physically transmitted. To check whether all written bytes have actually been transmitted, use the sp_output_waiting() function. To wait until all written bytes have actually been transmitted, use the sp_drain() function.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]bufBuffer containing the bytes to write. Must not be NULL.
[in]countMaximum number of bytes to write.
Returns
The number of bytes written on success, or a negative error code. The number of bytes returned may be any number from zero to the maximum that was requested.
Since
0.1.0
enum sp_return sp_output_waiting ( struct sp_port port)

Gets the number of bytes waiting in the output buffer.

Parameters
[in]portPointer to a port structure. Must not be NULL.
Returns
Number of bytes waiting on success, a negative error code otherwise.
Since
0.1.0