README

   1 ----------------------------------------------------------------
   2 libserialport: cross-platform library for accessing serial ports
   3 ----------------------------------------------------------------
   4
   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.
   7
   8 By writing your serial code to use libserialport, you enable it to work
   9 transparently on any platform supported by the library.
  10
  11 The operations that are supported are:
  12
  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.
  18
  19 libserialport is an open source project released under the LGPL3+ license.
  20
  21 Status
  22 ======
  23
  24 The library should build and work on any Windows or Unix-based system. If it
  25 does not, please submit a bug.
  26
  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.
  30
  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.
  33
  34 Future
  35 ======
  36
  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.
  39
  40 Dependencies
  41 ============
  42
  43 On Linux, libudev is required. On other systems no other libraries are required.
  44
  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.
  48
  49 Building
  50 ========
  51
  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.
  54
  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.
  57
  58 API
  59 ===
  60
  61 The API is simple, and designed to be a minimal wrapper around the serial port
  62 support in each OS.
  63
  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.
  67
  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.
  72
  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.
  77
  78 Functions calls that succeed return SP_OK, which is equal to zero, or where
  79 otherwise documented a positive value.
  80
  81 The available functions are as follows:
  82
  83 Enumeration
  84 -----------
  85
  86 int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr);
  87
  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.
  91
  92  The result should be freed after use by calling sp_free_port().
  93
  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.
  98
  99 void sp_free_port(struct sp_port *port);
 100
 101  Frees a port structure obtained from sp_get_port_by_name().
 102
 103 int sp_list_ports(struct sp_port ***list_ptr);
 104
 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
 108  receive the result.
 109
 110  The result should be freed after use by calling sp_free_port_list().
 111
 112  Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 113           failure, or SP_ERR_ARG if an invalid pointer is passed. If any error
 114           is returned, the variable pointed to by list_ptr will be set to NULL.
 115           Otherwise, it will be set to point to the newly allocated array.
 116
 117 void sp_free_port_list(struct sp_port **list);
 118
 119  Frees a port list obtained from sp_list_ports().
 120
 121 Opening and closing ports
 122 -------------------------
 123
 124 int sp_open(struct sp_port *port, int flags);
 125
 126  Opens the specified serial port.
 127
 128  Parameters:
 129
 130   port:      Pointer to port structure.
 131   flags:     Flags to use when opening the serial port. Possible
 132              flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK.
 133
 134  Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation
 135           failure, or SP_ERR_ARG if an invalid port is passed.
 136
 137 int sp_close(struct sp_port *port);
 138
 139  Closes the specified serial port.
 140
 141  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 142           if an invalid port is passed.
 143
 144 Setting port parameters
 145 -----------------------
 146
 147 int sp_set_params(struct sp_port *port, int baudrate,
 148                               int bits, int parity, int stopbits,
 149                               int flowcontrol, int rts, int dtr);
 150
 151  Sets serial parameters for the specified serial port.
 152
 153  Parameters:
 154
 155   port:        Pointer to port structure.
 156   baudrate:    Baud rate to set.
 157   bits:        Number of data bits to use.
 158   parity:      Parity setting to use
 159                (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD)
 160   stopbits:    Number of stop bits to use (1 or 2).
 161   flowcontrol: Flow control setting to use
 162                (SP_FLOW_NONE, SP_FLOW_HARDWARE or SP_FLOW_SOFTWARE)
 163
 164  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 165           for invalid arguments.
 166
 167 Reading, writing and flushing data
 168 ----------------------------------
 169
 170 int sp_read(struct sp_port *port, const void *buf, size_t count)
 171
 172  Reads bytes from the specified serial port. Note that this function may
 173  return after reading less than the specified number of bytes; it is the
 174  user's responsibility to iterate as necessary in this case.
 175
 176  Parameters:
 177
 178   port:  Pointer to port structure.
 179   buf:   Buffer in which to store the bytes read.
 180   count: Maximum number of bytes to read.
 181
 182  Returns: The number of bytes read, SP_ERR_FAIL on failure,
 183           or SP_ERR_ARG for invalid arguments.
 184
 185 int sp_write(struct sp_port *port, const void *buf, size_t count)
 186
 187  Write bytes to the specified serial port. Note that this function may
 188  return after writing less than the specified number of bytes; it is the
 189  user's responsibility to iterate as necessary in this case.
 190
 191  Parameters:
 192
 193   port:  Pointer to port structure.
 194   buf:   Buffer containing the bytes to write.
 195   count: Maximum number of bytes to write.
 196
 197  Returns: The number of bytes written, SP_ERR_FAIL on failure,
 198           or SP_ERR_ARG for invalid arguments.
 199
 200 int sp_flush(struct sp_port *port);
 201
 202  Flushes serial port buffers.
 203
 204  Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG
 205           if an invalid port is passed.
 206
 207 Error handling
 208 --------------
 209
 210 int sp_last_error_code();
 211
 212  Gets the error code for a failed operation.
 213
 214  In order to obtain the correct result, this function should be called
 215  straight after the failure, before executing any other system operations.
 216
 217  Returns: The system's numeric code for the error that caused the last
 218           operation to fail.
 219
 220 char *sp_last_error_message();
 221
 222  Gets the error message for failed operation.
 223
 224  In order to obtain the correct result, this function should be called
 225  straight after the failure, before executing other system operations.
 226
 227  Returns: The system's message for the error that caused the last
 228           operation to fail. This string may be allocated by the function,
 229           and should be freed after use by calling sp_free_error_message.
 230
 231 void sp_free_error_message(char *message);
 232
 233  Frees the error message returned by sp_last_error_message().