libserialport API

Introduction

libserialport is a minimal library written in C that is intended to take care of the OS-specific details when writing software that uses serial ports.

By writing your serial code to use libserialport, you enable it to work transparently on any platform supported by the library.

The operations that are supported are:

• Port enumeration (obtaining a list of serial ports on the system)
• Opening, closing and querying ports
• Setting port parameters (baud rate, parity, etc.)
• Port signalling operations (modem control lines, breaks, etc.)
• Reading, writing, and flushing data
• Waiting for events
• Obtaining error information

libserialport is an open source project released under the LGPL3+ license.

API principles

The API is simple, and designed to be a minimal wrapper around the serial port support in each OS.

Most functions take a pointer to a struct sp_port, which represents a serial port. These structures are always allocated and freed by the library, using the functions in the Enumeration section.

Most functions have return type sp_return and can return only four possible error values:

• SP_ERR_ARG means that a function was called with invalid arguments. This implies a bug in the caller. The arguments passed would be invalid regardless of the underlying OS or serial device involved.
• SP_ERR_FAIL means that the OS reported a failure. The error code or message provided by the OS can be obtained by calling sp_last_error_code() or sp_last_error_message().
• SP_ERR_SUPP indicates that there is no support for the requested operation in the current OS, driver or device. No error message is available from the OS in this case. There is either no way to request the operation in the first place, or libserialport does not know how to do so in the current version.
• SP_ERR_MEM indicates that a memory allocation failed.

All of these error values are negative.

Calls that succeed return SP_OK, which is equal to zero. Some functions declared sp_return can also return a positive value for a successful numeric result, e.g. sp_blocking_read() or sp_blocking_write().