Pseudo terminals are very convenient for testing purposes, but they are
not fully compatible with real serial (or even usb-serial) hardware.
With the new option, some workarounds can be enabled to hide the
differences and increase compatibility. Although these workarounds
shouldn't cause any problems in production builds, the advise is to
disable this feature.
A few ioctl's are not supported for pseudo terminals. They fail with
EINVAL (Linux) or ENOTTY (Mac OS X). Since these specific error codes
should not occur under normal conditions, they are simply ignored when
pseudo terminal support is enabled.
The TIOCEXCL ioctl (exclusive access) is also problematic. The TIOCEXCL
setting is shared between the master and slave side of the pty. When the
setting is applied on the slave side, it persists for as long as the
master side remains open. The result is that re-opening the slave side
will fail with EBUSY, unless the process has root priviliges. Since this
is very inconvenient, the TIOCEXCL setting is not used when pseudo
terminal support is enabled.
With exclusive access mode, no further open() operations on the terminal
are permitted, except for a process with root priviliges. Non-root
processes will fail with EBUSY. This change will prevent other processes
from accidentally messing up the communication. It also makes the
behaviour similar to Windows, where serial ports are always opened with
exclusive access.
On Mac OS X (and probably the other BSD's too), the ioctl() syscall
takes an 'unsigned long' integer as the request parameter. On 64bit
systems this is a 64bit type, while on 32bit systems it's a 32bit type.
Some of the request constants are defined as 32 bit negative numbers.
Casting it to a 64bit value will perform a sign extension operation to
preserve the negative value. Because this results in a different request
code when interpreted as an unsigned integer, the ioctl() call fails
with ENOTTY. For example TIOCMBIS is defined as 0x8004746c and becomes
0xffffffff8004746 after the sign extension.
Linux 64bit is unaffected by this problem. None of the request constants
has the sign bit set, and thus the sign extension has no effect. For
example TIOCMBIS is defined as 0x5416.
By using an unsigned integer type, the sign extension can be avoided. We
use the 'unsigned long' type in case one of the request constants
happens to be defined as a 64bit number.
The public header files are moved to a new subdirectory, to separate
the definition of the public interface from the actual implementation.
Using an identical directory layout as the final installation has the
advantage that the example code can be build outside the project tree
without any modifications to the #include statements.
When using half-duplex communication (e.g. only a single wire for both
Tx and Rx) a data packet needs to be transmitted entirely before
attempting to switch into receiving mode.
For legacy serial hardware, the tcdrain() probably works as advertised,
and waits until the data has been transmitted. However for common
usb-serial converters, the hardware doesn't provide any feedback to the
driver, and the tcdrain() function can only wait until the data has been
transmitted to the usb-serial chip. There is no guarantee that the data
has actually been transmitted by the usb-serial chip.
As a workaround, we wait at least the minimum amount of time required to
transmit the data packet over a serial line, taking into account the
current configuration.
On Mac OS X they disable the definition of the timeval macros and on
Linux they are defined by default. Thus removing them makes everything
work on both platforms.
