libserialport  unreleased development snapshot
cross-platform library for accessing serial ports
 All Data Structures Files Functions Variables Enumerations Enumerator Modules Pages
Functions
Configuration

Setting and querying serial port parameters. More...

Functions

enum sp_return sp_new_config (struct sp_port_config **config_ptr)
 Allocate a port configuration structure. More...
 
void sp_free_config (struct sp_port_config *config)
 Free a port configuration structure. More...
 
enum sp_return sp_get_config (struct sp_port *port, struct sp_port_config *config)
 Get the current configuration of the specified serial port. More...
 
enum sp_return sp_set_config (struct sp_port *port, const struct sp_port_config *config)
 Set the configuration for the specified serial port. More...
 
enum sp_return sp_set_baudrate (struct sp_port *port, int baudrate)
 Set the baud rate for the specified serial port. More...
 
enum sp_return sp_get_config_baudrate (const struct sp_port_config *config, int *baudrate_ptr)
 Get the baud rate from a port configuration. More...
 
enum sp_return sp_set_config_baudrate (struct sp_port_config *config, int baudrate)
 Set the baud rate in a port configuration. More...
 
enum sp_return sp_set_bits (struct sp_port *port, int bits)
 Set the data bits for the specified serial port. More...
 
enum sp_return sp_get_config_bits (const struct sp_port_config *config, int *bits_ptr)
 Get the data bits from a port configuration. More...
 
enum sp_return sp_set_config_bits (struct sp_port_config *config, int bits)
 Set the data bits in a port configuration. More...
 
enum sp_return sp_set_parity (struct sp_port *port, enum sp_parity parity)
 Set the parity setting for the specified serial port. More...
 
enum sp_return sp_get_config_parity (const struct sp_port_config *config, enum sp_parity *parity_ptr)
 Get the parity setting from a port configuration. More...
 
enum sp_return sp_set_config_parity (struct sp_port_config *config, enum sp_parity parity)
 Set the parity setting in a port configuration. More...
 
enum sp_return sp_set_stopbits (struct sp_port *port, int stopbits)
 Set the stop bits for the specified serial port. More...
 
enum sp_return sp_get_config_stopbits (const struct sp_port_config *config, int *stopbits_ptr)
 Get the stop bits from a port configuration. More...
 
enum sp_return sp_set_config_stopbits (struct sp_port_config *config, int stopbits)
 Set the stop bits in a port configuration. More...
 
enum sp_return sp_set_rts (struct sp_port *port, enum sp_rts rts)
 Set the RTS pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_rts (const struct sp_port_config *config, enum sp_rts *rts_ptr)
 Get the RTS pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_rts (struct sp_port_config *config, enum sp_rts rts)
 Set the RTS pin behaviour in a port configuration. More...
 
enum sp_return sp_set_cts (struct sp_port *port, enum sp_cts cts)
 Set the CTS pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_cts (const struct sp_port_config *config, enum sp_cts *cts_ptr)
 Get the CTS pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_cts (struct sp_port_config *config, enum sp_cts cts)
 Set the CTS pin behaviour in a port configuration. More...
 
enum sp_return sp_set_dtr (struct sp_port *port, enum sp_dtr dtr)
 Set the DTR pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_dtr (const struct sp_port_config *config, enum sp_dtr *dtr_ptr)
 Get the DTR pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_dtr (struct sp_port_config *config, enum sp_dtr dtr)
 Set the DTR pin behaviour in a port configuration. More...
 
enum sp_return sp_set_dsr (struct sp_port *port, enum sp_dsr dsr)
 Set the DSR pin behaviour for the specified serial port. More...
 
enum sp_return sp_get_config_dsr (const struct sp_port_config *config, enum sp_dsr *dsr_ptr)
 Get the DSR pin behaviour from a port configuration. More...
 
enum sp_return sp_set_config_dsr (struct sp_port_config *config, enum sp_dsr dsr)
 Set the DSR pin behaviour in a port configuration. More...
 
enum sp_return sp_set_xon_xoff (struct sp_port *port, enum sp_xonxoff xon_xoff)
 Set the XON/XOFF configuration for the specified serial port. More...
 
enum sp_return sp_get_config_xon_xoff (const struct sp_port_config *config, enum sp_xonxoff *xon_xoff_ptr)
 Get the XON/XOFF configuration from a port configuration. More...
 
enum sp_return sp_set_config_xon_xoff (struct sp_port_config *config, enum sp_xonxoff xon_xoff)
 Set the XON/XOFF configuration in a port configuration. More...
 
enum sp_return sp_set_config_flowcontrol (struct sp_port_config *config, enum sp_flowcontrol flowcontrol)
 Set the flow control type in a port configuration. More...
 
enum sp_return sp_set_flowcontrol (struct sp_port *port, enum sp_flowcontrol flowcontrol)
 Set the flow control type for the specified serial port. More...
 

Detailed Description

Setting and querying serial port parameters.

Function Documentation

void sp_free_config ( struct sp_port_config config)

Free a port configuration structure.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
Since
0.1.0
enum sp_return sp_get_config ( struct sp_port port,
struct sp_port_config config 
)

Get the current configuration of the specified serial port.

The user should allocate a configuration structure using sp_new_config() and pass this as the config parameter. The configuration structure will be updated with the port configuration.

Any parameters that are configured with settings not recognised or supported by libserialport, will be set to special values that are ignored by sp_set_config().

Parameters
[in]portPointer to a port structure. Must not be NULL.
[out]configPointer to a configuration structure that will hold the result. Upon errors the contents of the config struct will not be changed. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_baudrate ( const struct sp_port_config config,
int *  baudrate_ptr 
)

Get the baud rate from a port configuration.

The user should allocate a variable of type int and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]baudrate_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_bits ( const struct sp_port_config config,
int *  bits_ptr 
)

Get the data bits from a port configuration.

The user should allocate a variable of type int and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]bits_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_cts ( const struct sp_port_config config,
enum sp_cts cts_ptr 
)

Get the CTS pin behaviour from a port configuration.

The user should allocate a variable of type enum sp_cts and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]cts_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_dsr ( const struct sp_port_config config,
enum sp_dsr dsr_ptr 
)

Get the DSR pin behaviour from a port configuration.

The user should allocate a variable of type enum sp_dsr and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]dsr_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_dtr ( const struct sp_port_config config,
enum sp_dtr dtr_ptr 
)

Get the DTR pin behaviour from a port configuration.

The user should allocate a variable of type enum sp_dtr and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]dtr_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_parity ( const struct sp_port_config config,
enum sp_parity parity_ptr 
)

Get the parity setting from a port configuration.

The user should allocate a variable of type enum sp_parity and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]parity_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_rts ( const struct sp_port_config config,
enum sp_rts rts_ptr 
)

Get the RTS pin behaviour from a port configuration.

The user should allocate a variable of type enum sp_rts and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]rts_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_stopbits ( const struct sp_port_config config,
int *  stopbits_ptr 
)

Get the stop bits from a port configuration.

The user should allocate a variable of type int and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]stopbits_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_get_config_xon_xoff ( const struct sp_port_config config,
enum sp_xonxoff xon_xoff_ptr 
)

Get the XON/XOFF configuration from a port configuration.

The user should allocate a variable of type enum sp_xonxoff and pass a pointer to this to receive the result.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[out]xon_xoff_ptrPointer to a variable to store the result. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_new_config ( struct sp_port_config **  config_ptr)

Allocate a port configuration structure.

The user should allocate a variable of type "struct sp_port_config *" and pass a pointer to this to receive the result. The variable will be updated to point to the new configuration structure. The structure is opaque and must be accessed via the functions provided.

All parameters in the structure will be initialised to special values which are ignored by sp_set_config().

The structure should be freed after use by calling sp_free_config().

Parameters
[out]config_ptrIf any error is returned, the variable pointed to by config_ptr will be set to NULL. Otherwise, it will be set to point to the allocated config structure. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_baudrate ( struct sp_port port,
int  baudrate 
)

Set the baud rate for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]baudrateBaud rate in bits per second.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_bits ( struct sp_port port,
int  bits 
)

Set the data bits for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]bitsNumber of data bits.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config ( struct sp_port port,
const struct sp_port_config config 
)

Set the configuration for the specified serial port.

For each parameter in the configuration, there is a special value (usually -1, but see the documentation for each field). These values will be ignored and the corresponding setting left unchanged on the port.

Upon errors, the configuration of the serial port is unknown since partial/incomplete config updates may have happened.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]configPointer to a configuration structure. Must not be NULL.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_baudrate ( struct sp_port_config config,
int  baudrate 
)

Set the baud rate in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]baudrateBaud rate in bits per second, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_bits ( struct sp_port_config config,
int  bits 
)

Set the data bits in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]bitsNumber of data bits, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_cts ( struct sp_port_config config,
enum sp_cts  cts 
)

Set the CTS pin behaviour in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]ctsCTS pin mode, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_dsr ( struct sp_port_config config,
enum sp_dsr  dsr 
)

Set the DSR pin behaviour in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]dsrDSR pin mode, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_dtr ( struct sp_port_config config,
enum sp_dtr  dtr 
)

Set the DTR pin behaviour in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]dtrDTR pin mode, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_flowcontrol ( struct sp_port_config config,
enum sp_flowcontrol  flowcontrol 
)

Set the flow control type in a port configuration.

This function is a wrapper that sets the RTS, CTS, DTR, DSR and XON/XOFF settings as necessary for the specified flow control type. For more fine-grained control of these settings, use their individual configuration functions.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]flowcontrolFlow control setting to use.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_parity ( struct sp_port_config config,
enum sp_parity  parity 
)

Set the parity setting in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]parityParity setting, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_rts ( struct sp_port_config config,
enum sp_rts  rts 
)

Set the RTS pin behaviour in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]rtsRTS pin mode, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_stopbits ( struct sp_port_config config,
int  stopbits 
)

Set the stop bits in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]stopbitsNumber of stop bits, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_config_xon_xoff ( struct sp_port_config config,
enum sp_xonxoff  xon_xoff 
)

Set the XON/XOFF configuration in a port configuration.

Parameters
[in]configPointer to a configuration structure. Must not be NULL.
[in]xon_xoffXON/XOFF mode, or -1 to retain the current setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_cts ( struct sp_port port,
enum sp_cts  cts 
)

Set the CTS pin behaviour for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]ctsCTS pin mode.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_dsr ( struct sp_port port,
enum sp_dsr  dsr 
)

Set the DSR pin behaviour for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]dsrDSR pin mode.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_dtr ( struct sp_port port,
enum sp_dtr  dtr 
)

Set the DTR pin behaviour for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]dtrDTR pin mode.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_flowcontrol ( struct sp_port port,
enum sp_flowcontrol  flowcontrol 
)

Set the flow control type for the specified serial port.

This function is a wrapper that sets the RTS, CTS, DTR, DSR and XON/XOFF settings as necessary for the specified flow control type. For more fine-grained control of these settings, use their individual configuration functions.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]flowcontrolFlow control setting to use.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_parity ( struct sp_port port,
enum sp_parity  parity 
)

Set the parity setting for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]parityParity setting.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_rts ( struct sp_port port,
enum sp_rts  rts 
)

Set the RTS pin behaviour for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]rtsRTS pin mode.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_stopbits ( struct sp_port port,
int  stopbits 
)

Set the stop bits for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]stopbitsNumber of stop bits.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0
enum sp_return sp_set_xon_xoff ( struct sp_port port,
enum sp_xonxoff  xon_xoff 
)

Set the XON/XOFF configuration for the specified serial port.

Parameters
[in]portPointer to a port structure. Must not be NULL.
[in]xon_xoffXON/XOFF mode.
Returns
SP_OK upon success, a negative error code otherwise.
Since
0.1.0