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 a serial
65 port. These structures are always allocated and freed by the library, using the
66 functions in the 'Enumeration' section below.
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 All of 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 Function 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 int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
88 Obtains a pointer to a new sp_port structure representing the named port. The
89 user should allocate a variable of type "struct sp_port *" and pass a pointer
90 to this to receive the result.
92 The result should be freed after use by calling sp_free_port().
94 Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
95 failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
96 is returned, the variable pointed to by port_ptr will be set to NULL.
97 Otherwise, it will be set to point to the newly allocated port.
99 void sp_free_port(struct sp_port *port);
101 Frees a port structure obtained from sp_get_port_by_name().
103 int sp_list_ports(struct sp_port ***list_ptr);
105 Lists the serial ports available on the system. The result obtained is an
106 array of pointers to sp_port structures, terminated by a NULL. The user should
107 allocate a variable of type "struct sp_port **" and pass a pointer to this to
110 The result should be freed after use by calling sp_free_port_list(). If a port
111 from the list is to be used after freeing the list, it must be copied first
112 using sp_copy_port().
114 Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
115 failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
116 is returned, the variable pointed to by list_ptr will be set to NULL.
117 Otherwise, it will be set to point to the newly allocated array.
119 int sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr);
121 Makes a new copy of a sp_port structure. The user should allocate a variable
122 of type "struct sp_port *" and pass a pointer to this to receive the result.
124 The copy should be freed after use by calling sp_free_port().
126 Returns: SP_OK on success, SP_ERR_MEM on allocation failure, or SP_ERR_ARG
127 if an invalid port or pointer is passed. If any error is returned,
128 the variable pointed to by copy_ptr will be set to NULL. Otherwise,
129 it will be set to point to the newly allocated copy.
131 void sp_free_port_list(struct sp_port **list);
133 Frees a port list obtained from sp_list_ports(). This will also free all
134 the sp_port structures referred to from the list; any that are to be retained
135 must be copied first using sp_copy_port().
137 Opening and closing ports
138 -------------------------
140 int sp_open(struct sp_port *port, int flags);
142 Opens the specified serial port.
146 port: Pointer to port structure.
147 flags: Flags to use when opening the serial port. Possible
148 flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK.
150 Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
151 failure, or SP_ERR_ARG if an invalid port is passed.
153 int sp_close(struct sp_port *port);
155 Closes the specified serial port.
157 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
158 if an invalid port is passed.
160 Setting port parameters
161 -----------------------
163 int sp_set_baudrate(struct sp_port *port, int baudrate)
165 Sets the baud rate for the specified serial port.
169 port: Pointer to port structure.
170 baud: Baud rate in bits per second.
172 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
173 for invalid arguments.
175 int sp_set_bits(struct sp_port *port, int bits)
177 Sets the number of data bits for the specified serial port.
181 port: Pointer to port structure.
182 bits: Number of data bits to use. Valid values are 5 to 8.
184 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
185 for invalid arguments.
187 int sp_set_parity(struct sp_port *port, int parity)
189 Sets the parity for the specified serial port.
193 port: Pointer to port structure.
194 parity: Parity setting to use.
195 (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
197 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
198 for invalid arguments.
200 int sp_set_stopbits(struct sp_port *port, int stopbits)
202 Sets the number of stop bits for the specified port.
206 port: Pointer to port structure.
207 stopbits: Number of stop bits to use (1 or 2).
209 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
210 for invalid arguments.
212 int sp_set_flowcontrol(struct sp_port *port, int flowcontrol)
214 Sets the flow control type for the specified serial port.
216 This function is a wrapper that sets the RTS, CTS, DTR, DSR and
217 XON/XOFF settings as necessary for the specified flow control
218 type. For more fine-grained control of these settings, use their
219 individual configuration functions or the sp_set_config() function.
223 port: Pointer to port structure.
224 flowcontrol: Flow control setting to use. Valid settings are:
226 SP_FLOWCONTROL_NONE: No flow control.
227 SP_FLOWCONTROL_XONXOFF: Software flow control using XON/XOFF characters.
228 SP_FLOWCONTROL_RTSCTS: Hardware flow control using RTS/CTS signals.
229 SP_FLOWCONTROL_DTRDSR: Hardware flow control using DTR/DSR signals.
231 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
232 for invalid arguments.
234 int sp_set_config(struct sp_port *port, struct sp_port_config *config)
236 Sets all parameters for the specified serial port.
238 The user should populate a struct sp_port_config, then pass a pointer to it
239 as the config parameter.
241 The fields of sp_port_config are:
243 int baudrate: Baud rate in bits per second.
244 int bits: Number of data bits to use. Valid values are 5 to 8.
245 int parity: Parity setting to use.
246 (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
247 int stopbits: Number of stop bits to use (1 or 2).
248 int rts: RTS pin mode.
249 (SP_RTS_ON, SP_RTS_OFF or SP_RTS_FLOW_CONTROL)
250 int cts: CTS pin mode.
251 (SP_CTS_IGNORE or SP_CTS_FLOW_CONTROL)
252 int dtr: DTR pin mode.
253 (SP_DTR_ON, SP_DTR_OFF or SP_DTR_FLOW_CONTROL)
254 int dsr: DSR pin mode.
255 (SP_DSR_IGNORE or SP_DSR_FLOW_CONTROL)
256 int xon_xoff: XON/XOFF flow control mode.
257 (SP_XONXOFF_DISABLED, SP_XONXOFF_IN,
258 SP_XONXOFF_OUT or SP_XONXOFF_INOUT)
260 To retain the current value of any setting, set the field to to a
263 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
264 for invalid arguments.
266 Reading, writing and flushing data
267 ----------------------------------
269 int sp_read(struct sp_port *port, const void *buf, size_t count)
271 Reads bytes from the specified serial port. Note that this function may
272 return after reading less than the specified number of bytes; it is the
273 user's responsibility to iterate as necessary in this case.
277 port: Pointer to port structure.
278 buf: Buffer in which to store the bytes read.
279 count: Maximum number of bytes to read.
281 Returns: The number of bytes read, SP_ERR_FAIL on failure,
282 or SP_ERR_ARG for invalid arguments.
284 int sp_write(struct sp_port *port, const void *buf, size_t count)
286 Write bytes to the specified serial port. Note that this function may
287 return after writing less than the specified number of bytes; it is the
288 user's responsibility to iterate as necessary in this case.
292 port: Pointer to port structure.
293 buf: Buffer containing the bytes to write.
294 count: Maximum number of bytes to write.
296 Returns: The number of bytes written, SP_ERR_FAIL on failure,
297 or SP_ERR_ARG for invalid arguments.
299 int sp_flush(struct sp_port *port);
301 Flushes serial port buffers.
303 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
304 if an invalid port is passed.
309 int sp_last_error_code();
311 Gets the error code for a failed operation.
313 In order to obtain the correct result, this function should be called
314 straight after the failure, before executing any other system operations.
316 Returns: The system's numeric code for the error that caused the last
319 char *sp_last_error_message();
321 Gets the error message for failed operation.
323 In order to obtain the correct result, this function should be called
324 straight after the failure, before executing other system operations.
326 Returns: The system's message for the error that caused the last
327 operation to fail. This string may be allocated by the function,
328 and should be freed after use by calling sp_free_error_message.
330 void sp_free_error_message(char *message);
332 Frees the error message returned by sp_last_error_message().