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]	port	Pointer to a port structure. Must not be NULL.
[out]	buf	Buffer in which to store the bytes read. Must not be NULL.
[in]	count	Requested number of bytes to read.
[in]	timeout_ms	Timeout 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]	port	Pointer to a port structure. Must not be NULL.
[out]	buf	Buffer in which to store the bytes read. Must not be NULL.
[in]	count	Maximum number of bytes to read. Must not be zero.
[in]	timeout_ms	Timeout 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]	port	Pointer to a port structure. Must not be NULL.
[in]	buf	Buffer containing the bytes to write. Must not be NULL.
[in]	count	Requested number of bytes to write.
[in]	timeout_ms	Timeout 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]

port

Pointer 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]	port	Pointer to a port structure. Must not be NULL.
[in]	buffers	Which 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]

port

Pointer 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]	port	Pointer to a port structure. Must not be NULL.
[out]	buf	Buffer in which to store the bytes read. Must not be NULL.
[in]	count	Maximum 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]	port	Pointer to a port structure. Must not be NULL.
[in]	buf	Buffer containing the bytes to write. Must not be NULL.
[in]	count	Maximum 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]

port

Pointer to a port structure. Must not be NULL.

Returns

Number of bytes waiting on success, a negative error code otherwise.

Since

0.1.0