ost::Serial(3)

📦 version 1.8.1, in ubuntu jammy

💖 ost::Serial(3) — Library Functions Manual 💖

🌸 NAME 🌸

ost::Serial — bestie, this is the base class for all the serial I/O services under APE. Everything else in the serial universe is literally built on top of it. 👑

✨ SYNOPSIS ✨

#include <serial.h>

Inherited by ost::SerialPort, and ost::TTYStream. (both of them!! the nepo babies of the serial world 🫶)

🎀 Public Types

enum Error { errSuccess = 0, errOpenNoTty, errOpenFailed, errSpeedInvalid, errFlowInvalid, errParityInvalid, errCharsizeInvalid, errStopbitsInvalid, errOptionInvalid, errResourceFailure, errOutput, errInput, errTimeout, errExtended }

enum Flow { flowNone, flowSoft, flowHard, flowBoth }

enum Parity { parityNone, parityOdd, parityEven }

enum Pending { pendingInput, pendingOutput, pendingError }

typedef enum Error Error
typedef enum Flow Flow
typedef enum Parity Parity
typedef enum Pending Pending

Four enums, four typedefs, zero notes. It's giving very "I said what I said." 💅

💅 Public Member Functions

virtual ~Serial() — the serial base class may literally be thrown as a result of an error, and the one who catches it may then choose to destroy the object. 💀
Serial & operator= (const Serial &from) — serial ports can also be duplicated with the assignment operator. copy-paste but make it ports ✨
Error setSpeed (unsigned long speed) — sets the serial port speed, for both input and output. one speed, no favorites.
Error setCharBits (int bits) — sets the character size.
Error setParity (Parity parity) — sets the parity mode.
Error setStopBits (int bits) — sets how many stop bits you want.
Error setFlowControl (Flow flow) — sets the flow control.
void toggleDTR (timeout_t millisec) — flips the DTR mode off for a moment.
void sendBreak (void) — sends the 'break' signal. dramatic much? sending a break, iconic 🎀
Error getErrorNumber (void) — the one you call from a 'catch' to grab the last error off a thrown serial.
char * getErrorString (void) — also a 'catch' bestie: this one hands you the user-set error string of a thrown serial.
int getBufferSize (void) — gets the 'buffer' size used for buffered operations.
virtual bool isPending (Pending pend, timeout_t timeout=TIMEOUT_INF) — checks the status of pending operations.

🧚 Protected Member Functions

void open (const char *fname) — opens the serial device.
void close (void) — closes the serial device.
virtual int aRead (char *Data, const int Length) — reads from the serial device.
virtual int aWrite (const char *Data, const int Length) — writes to the serial device.
Error error (Error error, char *errstr=NULL) — this service throws all the serial errors, and they usually pop off during the serial constructor. yes, during. rude.
void error (char *err) — this service throws application-defined serial errors, where the app-specific error code is a string.
void setError (bool enable) — turns the error handler on or off for throwing exceptions, by messing with the thrown flag.
int setPacketInput (int size, unsigned char btimer=0) — sets packet read mode, plus the 'size' of the packet read buffer.
int setLineInput (char newline=13, char nl1=0) — sets 'line buffering' read mode and tells it which newline character separates line records.
void restore (void) — puts the serial device back to the original settings it had at the time of open. we love a restore point 🫶
void flushInput (void) — flushes the input waiting queue.
void flushOutput (void) — flushes any pending output data.
void waitOutput (void) — waits until all the output has actually been sent. patience, queen.
void endSerial (void) — the default destructor for ending serial I/O services.
void initConfig (void) — initializes a newly opened serial file handle.
Serial () — this lets the later ttystream class open and close a serial device.
Serial (const char *name) — a serial object can be constructed from a named file on the file system.

🌈 Protected Attributes

HANDLE dev
int bufsize

(yes bestie, no description, they're just there. mysterious. lowkey main character energy 🦋)

💜 Detailed Description 💜

The Serial class is used as the base for all serial I/O services under APE. fr fr.

A serial is a system serial port, and it's used for either line or packet based data input. Serial ports may also be 'streamable' in a derived form. obsessed.

The Common C++ serial I/O classes are what you use to manage serial devices and implement serial device protocols. From Common C++'s point of view, serial devices are supported by the underlying Posix-specified 'termios' call interface. that's the whole vibe.

The serial I/O base class holds a descriptor to a serial device and provides an exception handling interface for every serial I/O class. It's also the place where serial I/O properties get specified, like communication speed, flow control, data size, and parity. But the 'Serial' base class is not itself directly used in application development. nope. it's the foundation, not the furniture.

Common C++ Serial I/O is itself split into two conceptual modes: frame oriented and line oriented I/O. Both of them use the underlying tty driver's ability to buffer data and hand back 'ready' status from when select hits either a specified number of bytes or a newline record — by manipulating the termios c_cc fields the right way. The glow-up here? A given thread servicing a serial port can block and wait instead of having to constantly poll or read every single byte the literal instant it shows up at the serial port. no more doom-scrolling bytes. 😭

⭐ Author

David Sugar dyfet@ostel.com

base class for all serial I/O services.

🦋 Member Typedef Documentation 🦋

typedef enum Error ost::Serial::Error
typedef enum Flow ost::Serial::Flow
typedef enum Parity ost::Serial::Parity
typedef enum Pending ost::Serial::Pending

🌸 Member Enumeration Documentation 🌸

`enum ost::Serial::Error`

Enumerator:

errSuccess
errOpenNoTty
errOpenFailed
errSpeedInvalid
errFlowInvalid
errParityInvalid
errCharsizeInvalid
errStopbitsInvalid
errOptionInvalid
errResourceFailure
errOutput
errInput
errTimeout
errExtended

`enum ost::Serial::Flow`

Enumerator:

flowNone
flowSoft
flowHard
flowBoth

`enum ost::Serial::Parity`

Enumerator:

parityNone
parityOdd
parityEven

`enum ost::Serial::Pending`

Enumerator:

pendingInput
pendingOutput
pendingError

🎀 Constructor & Destructor Documentation 🎀

`ost::Serial::Serial () [inline], [protected]`

This allows the later ttystream class to open and close a serial device.

`ost::Serial::Serial (const char * name) [protected]`

A serial object may be constructed from a named file on the file system. Heads up though: this named device must be 'isatty()'.

Parameters

name of file.

`virtual ost::Serial::~Serial () [virtual]`

The serial base class may be 'thrown' as a result of an error, and the 'catcher' may then choose to destroy the object. By making sure the socket base class is a virtual destructor, we can make sure the full object gets properly terminated. queen of cleaning up after herself 💅

💖 Member Function Documentation 💖

okay bestie, this is the part where we go function by function. every single one, no skips, no cap. let's get into it 💅

`virtual int ost::Serial::aRead (char * Data, const int Length) [protected], [virtual]`

Reads from the serial device. like, it's pulling bytes out for you.

Parameters:

Data — points to the character buffer that receives data. Buffers MUST be at least Length + 1 bytes in size. no negotiating on that one, bestie 😭
Length — number of bytes to read.

`virtual int ost::Serial::aWrite (const char * Data, const int Length) [protected], [virtual]`

Writes to the serial device. sending it out into the world ✨

Parameters:

Data — point to character buffer containing data to write. Buffers MUST 💀
Length — number of bytes to write.

`void ost::Serial::close (void) [protected]`

Closes the serial device. bye bye 👋

`void ost::Serial::endSerial (void) [protected]`

Used as the default destructor for ending serial I/O services. It will restore the port to it's original state. so like, it puts everything back how it found it, iconic behavior 🎀

`void ost::Serial::error (char * err) [inline], [protected]`

This service is used to thow application defined serial errors where the application specific error code is a string.

Parameters:

err — string or message to pass.

References ost::error().

`Error ost::Serial::error (Error error, char * errstr = NULL) [protected]`

This service is used to throw all serial errors which usually occur during the serial constructor.

Parameters:

error — defined serial error id.
errstr — string or message to optionally pass.

`void ost::Serial::flushInput (void) [protected]`

Used to flush the input waiting queue. clear it out, bestie 🧹

`void ost::Serial::flushOutput (void) [protected]`

Used to flush any pending output data. same energy, output edition 💅

`int ost::Serial::getBufferSize (void) [inline]`

Get the 'buffer' size for buffered operations. This can be used when setting packet or line read modes to determine how many bytes to wait for in a given read call.

Returns: number of bytes used for buffering.

`Error ost::Serial::getErrorNumber (void) [inline]`

Often used by a 'catch' to fetch the last error of a thrown serial.

Returns: error numbr of last Error.

`char* ost::Serial::getErrorString (void) [inline]`

Often used by a 'catch' to fetch the user set error string of a thrown serial.

Returns: string for error message.

`void ost::Serial::initConfig (void) [protected]`

Used to initialize a newly opened serial file handle. You should set serial properties and DTR manually before first use. so like, don't skip that step, bestie 🙈

`virtual bool ost::Serial::isPending (Pending pend, timeout_t timeout = TIMEOUT_INF) [virtual]`

Get the status of pending operations. This can be used to examine if input or output is waiting, or if an error has occured on the serial device.

Returns: true if ready, false if timeout.

Parameters:

pend — ready check to perform.
timeout — in milliseconds.

Reimplemented in ost::TTYStream.

`void ost::Serial::open (const char * fname) [protected]`

Opens the serial device. let's goooo 🔥

Parameters:

fname — Pathname of device to open

`Serial& ost::Serial::operator= (const Serial & from)`

Serial ports may also be duplecated by the assignment operator. copy paste but make it serial port energy ✨

`void ost::Serial::restore (void) [protected]`

Restore serial device to the original settings at time of open. we love a glow-up back to factory settings 💖

`void ost::Serial::sendBreak (void)`

Send the 'break' signal. not me sending break like it's a text 💀

`Error ost::Serial::setCharBits (int bits)`

Set character size.

Returns: 0 on success.

Parameters:

bits — character size to use (usually 7 or 8).

`void ost::Serial::setError (bool enable) [inline], [protected]`

This method is used to turn the error handler on or off for 'throwing' execptions by manipulating the thrown flag.

Parameters:

enable — true to enable handler.

`Error ost::Serial::setFlowControl (Flow flow)`

Set flow control.

Returns: 0 on success.

Parameters:

flow — control mode.

`int ost::Serial::setLineInput (char newline = 13, char nl1 = 0) [protected]`

Set 'line buffering' read mode and specifies the newline character to be used in seperating line records. isPending can then be used to wait for an entire line of input.

Parameters:

newline — newline character.
nl1 — EOL2 control character.

Returns: size of conical input buffer.

`int ost::Serial::setPacketInput (int size, unsigned char btimer = 0) [protected]`

Set packet read mode and 'size' of packet read buffer. This sets VMIN to x. VTIM is normally set to '0' so that 'isPending()' can wait for an entire packet rather than just the first byte.

Returns: actual buffer size set.

Parameters:

size — of packet read request.
btimer — optional inter-byte data packet timeout.

`Error ost::Serial::setParity (Parity parity)`

Set parity mode.

Returns: 0 on success.

Parameters:

parity — mode.

`Error ost::Serial::setSpeed (unsigned long speed)`

Set serial port speed for both input and output.

Returns: 0 on success.

Parameters:

speed — to select. 0 signifies modem 'hang up'.

`Error ost::Serial::setStopBits (int bits)`

Set number of stop bits.

Returns: 0 on success.

Parameters:

bits — stop bits.

`void ost::Serial::toggleDTR (timeout_t millisec)`

Set the DTR mode off momentarily.

Parameters:

millisec — number of milliseconds.

`void ost::Serial::waitOutput (void) [protected]`

Used to wait until all output has been sent. patience, bestie, patience 🧘

🦋 Member Data Documentation 🦋

int ost::Serial::bufsize [protected]
HANDLE ost::Serial::dev [protected]
bool ost::Serial::linebuf
bool ost::Serial::thrown

👑 Author 👑

Generated automatically by Doxygen for GNU CommonC++ from the source code.

💖 that's the whole manual page, bestie! auto-generated by Doxygen for GNU CommonC++ from the source code, and the footer vibe is GNU CommonC++ • Sun Dec 27 2020 • ost::Serial(3). periodt. slay. 🎀✨

📦 where this page comes from

ubuntu jammy: libcommoncpp2-doc 1.8.1-10
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms