Reading, writing, and flushing data

Functions
enum sp_return	sp_blocking_read (struct sp_port *port, void *buf, size_t count, unsigned int timeout)
	Read bytes from the specified serial port, blocking until complete. 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)
	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

Function Documentation

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

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

port	Pointer to port structure.
buf	Buffer in which to store the bytes read.
count	Requested number of bytes to read.
timeout	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

enum sp_return sp_blocking_write	(	struct sp_port *	port,
		const void *	buf,
		size_t	count,
		unsigned int	timeout
	)

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

port	Pointer to port structure.
buf	Buffer containing the bytes to write.
count	Requested number of bytes to write.
timeout	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 occured.

Since

0.1.0

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

port	Pointer to port structure.

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

port	Pointer to port structure.
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

port	Pointer to port structure.

Returns

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

Since

0.1.0

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

port	Pointer to port structure.
buf	Buffer in which to store the bytes read.
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

port	Pointer to port structure.
buf	Buffer containing the bytes to write.
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

port	Pointer to port structure.

Returns

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

Since

0.1.0