1 ----------------------------------------------------------------
2 libserialport: cross-platform library for accessing serial ports
3 ----------------------------------------------------------------
5 libserialport is a minimal library written in C that is intended to take care
6 of the OS-specific details when writing software that uses serial ports.
8 By writing your serial code to use libserialport, you enable it to work
9 transparently on any platform supported by the library.
11 The operations that are supported are:
13 - Port enumeration (obtaining a list of serial ports on the system).
14 - Opening and closing ports.
15 - Setting port parameters (baud rate, parity, etc).
16 - Reading, writing and flushing data.
17 - Obtaining error information.
19 libserialport is an open source project released under the LGPL3+ license.
24 The library should build and work on any Windows or Unix-based system. If it
25 does not, please submit a bug.
27 Enumeration is currently only implemented on Windows, Mac OS X and Linux. On
28 other systems enumeration will return no results, but ports can still be opened
29 by name and then used.
31 If you know how to enumerate available ports on another OS, please submit a bug
32 with this information, or better still a patch implementing it.
37 Future versions will add additional API calls for obtaining metadata about a
38 port, e.g. for USB devices the USB VID and PID of the underlying device.
43 On Linux, libudev is required. On other systems no other libraries are required.
45 The libudev dependency could be eliminated in favour of direct sysfs queries at
46 the cost of some brevity. This is not currently a priority but if you feel like
47 doing this feel free to submit a patch.
52 The package uses a GNU style build system and requires a Unix style shell.
53 On Windows it can be built with the MinGW toolchain and MSYS environment.
55 Run "./autogen.sh" to generate the build system, "./configure" to setup, then
56 "make" to build the library and "make install" to install it.
61 The API is simple, and designed to be a minimal wrapper around the serial port
64 Most functions take a pointer to a struct sp_port, which represents an open
65 port. This structure should be allocated by the user and is populated by
66 sp_open(). It can be freed safely after sp_close().
68 All functions can return only three possible error values. SP_ERR_ARG indicates
69 the function was called with invalid arguments. SP_ERR_FAIL indicates that the
70 OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed.
71 Aoth these error values are negative.
73 When SP_ERR_FAIL is returned, an error code or string description of the error
74 can be obtained by calling sp_last_error_code() or sp_last_error_message(). The
75 error code or message is that provided by the OS; libserialport does not define
76 any error codes or messages of its own.
78 Functions calls that succeed return SP_OK, which is equal to zero, or where
79 otherwise documented a positive value.
81 The available functions are as follows:
86 char **sp_list_ports();
88 Lists the serial ports available on the system. The value returned is an array
89 of port names as C strings, terminated by a NULL. It should be freed after use
90 by calling sp_free_port_list().
92 void sp_free_port_list(char **list);
94 Frees the data structure returned by sp_list_ports().
96 Opening and closing ports
97 -------------------------
99 int sp_open(struct sp_port *port, char *portname, int flags);
101 Opens the specified serial port.
105 port: Pointer to empty port structure, allocated by caller.
106 portname: Name of port to open.
107 flags: Flags to use when opening the serial port. Possible
108 flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK.
110 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
111 if an invalid port or name is passed.
113 int sp_close(struct sp_port *port);
115 Closes the specified serial port.
117 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
118 if an invalid port is passed.
120 Setting port parameters
121 -----------------------
123 int sp_set_params(struct sp_port *port, int baudrate,
124 int bits, int parity, int stopbits,
125 int flowcontrol, int rts, int dtr);
127 Sets serial parameters for the specified serial port.
131 port: Pointer to port structure.
132 baudrate: Baud rate to set.
133 bits: Number of data bits to use.
134 parity: Parity setting to use
135 (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
136 stopbits: Number of stop bits to use (1 or 2).
137 flowcontrol: Flow control setting to use
138 (SP_FLOW_NONE, SP_FLOW_HARDWARE or SP_FLOW_SOFTWARE)
140 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
141 for invalid arguments.
143 Reading, writing and flushing data
144 ----------------------------------
146 int sp_read(struct sp_port *port, const void *buf, size_t count)
148 Reads a number of bytes from the specified serial port.
152 port: Pointer to port structure.
153 buf: Buffer in which to store the bytes read.
154 count: Number of bytes to read.
156 Returns: The number of bytes read, SP_ERR_FAIL on failure,
157 or SP_ERR_ARG for invalid arguments.
159 int sp_write(struct sp_port *port, const void *buf, size_t count)
161 Writes a number of bytes to the specified serial port.
165 port: Pointer to port structure.
166 buf: Buffer containing the bytes to write.
167 count: Number of bytes to write.
169 Returns: The number of bytes written, SP_ERR_FAIL on failure,
170 or SP_ERR_ARG for invalid arguments.
172 int sp_flush(struct sp_port *port);
174 Flushes serial port buffers.
176 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
177 if an invalid port is passed.
182 int sp_last_error_code();
184 Gets the error code for a failed operation.
186 In order to obtain the correct result, this function should be called
187 straight after the failure, before executing any other system operations.
189 Returns: The system's numeric code for the error that caused the last
192 char *sp_last_error_message();
194 Gets the error message for failed operation.
196 In order to obtain the correct result, this function should be called
197 straight after the failure, before executing other system operations.
199 Returns: The system's message for the error that caused the last
200 operation to fail. This string may be allocated by the function,
201 and should be freed after use by calling sp_free_error_message.
203 void sp_free_error_message(char *message);
205 Frees the error message returned by sp_last_error_message().