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 serial
65 port. This structure is obtained from the array returned by sp_list_ports().
67 All functions can return only three possible error values. SP_ERR_ARG indicates
68 the function was called with invalid arguments. SP_ERR_FAIL indicates that the
69 OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed.
70 All of these error values are negative.
72 When SP_ERR_FAIL is returned, an error code or string description of the error
73 can be obtained by calling sp_last_error_code() or sp_last_error_message(). The
74 error code or message is that provided by the OS; libserialport does not define
75 any error codes or messages of its own.
77 Functions calls that succeed return SP_OK, which is equal to zero, or where
78 otherwise documented a positive value.
80 The available functions are as follows:
85 int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
87 Obtains a pointer to a new sp_port structure representing the named port. The
88 user should allocate a variable of type "struct sp_port *" and pass a pointer
89 to this to receive the result.
91 The result should be freed after use by calling sp_free_port().
93 Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
94 failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
95 is returned, the variable pointed to by port_ptr will be set to NULL.
96 Otherwise, it will be set to point to the newly allocated port.
98 void sp_free_port(struct sp_port *port);
100 Frees a port structure obtained from sp_get_port_by_name().
102 int sp_list_ports(struct sp_port ***list_ptr);
104 Lists the serial ports available on the system. The result obtained is an
105 array of pointers to sp_port structures, terminated by a NULL. The user should
106 allocate a variable of type "struct sp_port **" and pass a pointer to this to
109 The result should be freed after use by calling sp_free_port_list().
111 Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
112 failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
113 is returned, the variable pointed to by list_ptr will be set to NULL.
114 Otherwise, it will be set to point to the newly allocated array.
116 void sp_free_port_list(struct sp_port **list);
118 Frees a port list obtained from sp_list_ports().
120 Opening and closing ports
121 -------------------------
123 int sp_open(struct sp_port *port, int flags);
125 Opens the specified serial port.
129 port: Pointer to port structure.
130 flags: Flags to use when opening the serial port. Possible
131 flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK.
133 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
134 if an invalid port is passed.
136 int sp_close(struct sp_port *port);
138 Closes the specified serial port.
140 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
141 if an invalid port is passed.
143 Setting port parameters
144 -----------------------
146 int sp_set_params(struct sp_port *port, int baudrate,
147 int bits, int parity, int stopbits,
148 int flowcontrol, int rts, int dtr);
150 Sets serial parameters for the specified serial port.
154 port: Pointer to port structure.
155 baudrate: Baud rate to set.
156 bits: Number of data bits to use.
157 parity: Parity setting to use
158 (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
159 stopbits: Number of stop bits to use (1 or 2).
160 flowcontrol: Flow control setting to use
161 (SP_FLOW_NONE, SP_FLOW_HARDWARE or SP_FLOW_SOFTWARE)
163 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
164 for invalid arguments.
166 Reading, writing and flushing data
167 ----------------------------------
169 int sp_read(struct sp_port *port, const void *buf, size_t count)
171 Reads bytes from the specified serial port. Note that this function may
172 return after reading less than the specified number of bytes; it is the
173 user's responsibility to iterate as necessary in this case.
177 port: Pointer to port structure.
178 buf: Buffer in which to store the bytes read.
179 count: Maximum number of bytes to read.
181 Returns: The number of bytes read, SP_ERR_FAIL on failure,
182 or SP_ERR_ARG for invalid arguments.
184 int sp_write(struct sp_port *port, const void *buf, size_t count)
186 Write bytes to the specified serial port. Note that this function may
187 return after writing less than the specified number of bytes; it is the
188 user's responsibility to iterate as necessary in this case.
192 port: Pointer to port structure.
193 buf: Buffer containing the bytes to write.
194 count: Maximum number of bytes to write.
196 Returns: The number of bytes written, SP_ERR_FAIL on failure,
197 or SP_ERR_ARG for invalid arguments.
199 int sp_flush(struct sp_port *port);
201 Flushes serial port buffers.
203 Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
204 if an invalid port is passed.
209 int sp_last_error_code();
211 Gets the error code for a failed operation.
213 In order to obtain the correct result, this function should be called
214 straight after the failure, before executing any other system operations.
216 Returns: The system's numeric code for the error that caused the last
219 char *sp_last_error_message();
221 Gets the error message for failed operation.
223 In order to obtain the correct result, this function should be called
224 straight after the failure, before executing other system operations.
226 Returns: The system's message for the error that caused the last
227 operation to fail. This string may be allocated by the function,
228 and should be freed after use by calling sp_free_error_message.
230 void sp_free_error_message(char *message);
232 Frees the error message returned by sp_last_error_message().