The Windshield in a World of Bugs^*

General Purpose Library   Networking Library   C++ Library   Applications

Software Conventions   Porting and Supported Platforms   Acknowledgements   On the Shelf

Design/Implementation/Documentation Conventions

My library software follows certain conventions that you might find useful to know when using or examining the software:

• In general, each source file ("obj_util.c") is a package of functions that operate on a particular type of object; e.g., a network connection, a hash table, etc. Associated with each package is a header file ("obj_util.h") which defines an opaque handle for objects of the given type, any global variables, and function prototypes for public functions in the package.


• Naming conventions for the functions that operate on objects are as follows:
  
  
  • objCreate() creates a particular type of object and returns a handle that is passed to other functions in the package.
  • objDestroy() destroys an object.
  • objAdd() and objDelete() are used to add and delete items in a container object; e.g., elements of a list, entries in a hash table, etc.


• I/O packages typically include the following functions:
  
  
  • objOpen() and objClose() create and destroy, respectively, objects of the given type.
  • objFd() returns the underlying UNIX file descriptor for an I/O object.
  • objIsReadable(), objIsWriteable(), and objIsUp() poll an I/O object.
  • objName() returns the name of an I/O object.
  • objRead() and objWrite() perform actual I/O on an object.


• Most of the library functions return an errno(3) status code as their value: zero indicates no error, EINVAL indicates an invalid argument, etc.


• aperror() is a perror(3)-like function that formats and prints a user error message on stderr, followed by the system error message corresponding to the current value of errno. aperror() output is enabled by setting a global variable, aperror_print, to a non-zero value.
  
  My library functions use aperror() to report errors (in addition to returning an error code). A rather primitive mechanism for reporting errors? You betcha - but at least it's there!
  
  Since aperror_print is initialized to zero, you normally won't see any error messages. My programs usually enable aperror() output during initialization (when configuration errors and such like may occur) and disable it thereafter. A command line option, "-aperror", is usually available to override this behavior.


• Most of the packages have a global obj_util_debug variable that can be set to a non-zero value to enable debug output to stdout.

More to follow when I think of it ...

Porting and Supported Platforms

In writing my software, I try make it as portable as possible. I make use of ANSI C libraries and header files as much as I can. Function declarations are made in both ANSI C and non-ANSI C form, so the code will compile whether your compiler is ANSI C-compliant or not. I've attempted to isolate compiler and OS dependencies in a header file, pragmatics.h, except for some networking and time definitions that are found in skt_util.h and tv_util.h, respectively.

The operating systems I used on my last project were:

• Linux (RedHat 6.2, 7.2, and Fedora Core 2)
• Solaris (SunOS 5.5 through SunOS 8 on SPARC and x86 platforms)
• Windows (98, NT, and 2000)

In previous years, I used: SunOS 4.1.3 (on SPARC platforms), HP/UX, Lynx OS 2.4 (on a PowerPC), and VxWorks (on 68040-based systems). Even before that, I was on a project for which we ported earlier versions of much of this software from UNIX to VMS (VAX C and UCX TCP/IP).

The software distributions generally include the following Makefiles:

• Makefile.linux - for building under Linux using gcc. The Linux Makefiles may also be used with Cygwin.
• Makefile.solaris - for building under Solaris using cc or gcc. Support for cc may not work (or be missing from newer Makefiles) since I only have access to an OpenSolaris 10 machine now.
• Makefile.tcc - for building under Linux using the blindingly fast Tiny C Compiler (TCC).
• Makefile.freebsd - for building under FreeBSD. I briefly had my home computer dual-booting FreeBSD. It was never able to run my monitor at greater than 800x600 resolution, so I finally ditched FreeBSD for now.
• Makefile.palm68k - for building PalmOS libraries and standard I/O applications under Linux using PRC-Tools (GCC for Palm OS).
• Makefile.nds - for building Nintendo DS libraries and standard I/O applications using the devkitPro tool chain (GCC for ARM).
• vaxc.com - for building under VAX/VMS.
• *.dsw, *.dsp - Microsoft Visual C++ 6.0 workspace and project files, respectively.
• *.sln, *.vcproj - Microsoft Studio 2003 solution and project files, respectively.

I mostly work on Linux and Solaris machines, so my code is most heavily exercised under those operating systems. On Windows, I build static libraries and link them to console applications. I used to have access to an old VMS 5.5 VAXstation, so I was able to compile and test my programs under VMS/UCX.

With respect to PalmOS, I built my libraries with PRC-Tools and I created a number of StdIOPalm applications that use the libraries. Click on the Palm Pilot thumbnail to see the screen output from a port scanner, scanet. I have not worked with PalmOS for a few years now and the Palm world has moved on to newer operating systems.

Acknowledgements

Thanks to the following people for bug and porting reports:

• Tom Dahm - ported LIBGPL's regular expression package to Linux, but later switched to Perl. regular expressions. (NetMechanic, featured in Inter@ctive Week, Wayback Machine)
• Mathieu Frenette - ported the regular expression utilities to Windows 95 for a file manager he called "File Name Juggler". He also reported a bug in rex_wild(); if I was Donald Knuth, I'd have payed him for it!
• Örjan Leringe - ported the regular expression utilities to MS-DOS (Borland C version 3.1) and Windows (95? Visual C version 5).
• The XCorpus Toolkit Environment (Wayback Machine) includes my hash table package. (PostScript)
• Thierry Le Blond has modified the hash table package to support fixed-length, binary keys.
• Nicolas Boghossian (Wayback Machine), the man of 1000 E-mail addresses, reported a memory allocation bug in rex_replace().
• $cott Dybiec - ported LIBGPL to Linux and AIX. (Human Factor, Wayback Machine)
• Laura Tweedy appeared to be using some of my software in a COBOL-to-C translator (Wayback Machine).
• Kevin Esteb - corrected the regular expression utilities to handle full 8-bit characters. He also ported LIBGPL to Linux and parts of it to Alpha VMS 7.1.
• Brandon W. Yuille - found an embarrassing carry mistake in my timespec and timeval addition functions.

I don't have the changes required for the various ports, but at least I know it's possible to port the code to the various platforms with relatively little trouble. My apologies to anyone I've left out, including those who reported bugs (e.g., in the quadword utilities and in the IPC utilities) before I started keeping a list here.

General Purpose Library (csoft.tgz, 873K  -  csoft.zip, 1246K)

Licensing: The CSOFT libraries and applications are covered by the MIT License. Basically, you are free to use the software however you see fit, in commercial or non-commerical applications. I only ask that, if your time and inclination permit, you report any bugs or portability problems you encounter. Suggestions for improvements and enhancements are welcome, but I do not guarantee I will act upon them.

Command Line Processing

opt_util - full-word option scanning package for UNIX-style command lines or strings.

Data Structures

gsc_util - generic depth-first and breadth-first graph search package.

hash_util - hash table creation/search package.

list_util - generic list handling package.

tpl_util - N-tuple creation and element retrieval.

Error Reporting

aperror - perror(3)-like error reporting function.

Files

drs_util - directory scanning package.

fnm_util - file name parsing package.

Interprocess Communication

The IPC packages provide named message queues, semaphores, and shared memory segments under UNIX and VxWorks. Earlier versions of the semaphore and shared memory packages were ported to VMS by Fred Shaklan and myself; message queues were not needed, but they could have been easily emulated using mailboxes. If I ever work on VMS again, I'll port the new packages; the package APIs are operating system-independent.

msq_util - high-level interface to named message queues (UNIX and VxWorks).

nob_util - named objects database package.

sem_util - high-level interface to named semaphores (UNIX and VxWorks).

shm_util - high-level interface to named shared memory (UNIX and VxWorks).

Memory Management

meo_util - memory operations.

String Manipulation

get_util - miscellaneous string scanning functions.

rex_util - full-featured regular expression matching and substitution package.

str_util - miscellaneous string handling functions.

wcs_util - wide-character string handling functions.

Time

bmw_util - benchmarking package.

ts_util - POSIX timespec manipulation package.

tv_util - UNIX timeval manipulation package.

Miscellaneous

bit_util - bit manipulation functions.

id3_util - ID3 tag access functions.

xqt_util - shell execution package (high-level interface to UNIX shell or VMS CLI).

Networking

The following packages provide high-level, but powerful, interfaces to TCP/IP and UDP/IP networking:

tcp_util - high-level interface for TCP/IP network socket I/O.

udp_util - high-level interface for UDP/IP network socket I/O.

And the following packages implement higher-level protocols layered on top of the TCP_UTIL package:

lfn_util - high-level interface for LF-terminated network I/O.

nft_util - FTP server framework (UNIX, VMS, and VxWorks).

xnet_util - high-level interface to xdr(3)-based network I/O.

The IOX package simplifies the writing of I/O-event-driven applications (e.g., network servers):

iox_util - I/O and timer event dispatcher.

port_util - simple listening ports for IOX dispatcher-based network servers.

The remaining packages are an assortment of networking support functions:

net_util - miscellaneous network functions.

skt_util - socket support functions.

Version-Independent Messages

These three packages implement version-independent messages as described in Appendix B of Robert Martin's Designing Object-Oriented C++ Applications Using the Booch Method. (What he calls attributed data trees, I call name/value lists.) VIM network streams are layered on top of the TCP_UTIL package.

nvp_util - name/value pairs.

nvl_util - lists of name/value pairs.

vim_util - version-independent message streams.

CORBA-Lite

The CORBA-Lite packages provide a lightweight implementation of CORBA TCP/IP messaging.

coli_util - CORBA messaging functions.

comx_util - CORBA marshaling functions.

gimx_util - GIOP marshaling utilities.

iiop_util - Internet Inter-ORB Protocol (IIOP) streams.

bomx_util (idl.h) - GNOME Bonobo 2.0 marshaling functions.

damx_util (idl.h) - Data Acquisition from Industrial Systems (DAIS) marshaling functions.

ddmx_util (idl.h) - Data Distribution Service for Real-Time Systems (DDS) marshaling functions.

lemx_util (idl.h) - Laboratory Equipment Control Interface Specification (LECIS) marshaling functions.

C++ Remote Access Library (cppsoft.zip, 842K)

The ZIP file contains 3 library directories:

liberal - the general-purpose networking code.

libxdr - an XDR library for use on platforms (e.g., Windows) that don't have an XDR library.

regex - the BOOST regular expression library for use on platforms (e.g., Windows) that don't have a regex(3) library.

The latter two libraries can be dropped if you build a subset of the liberal library. The classes in this library generally have counterparts in the libgpl library above.

Dispatcher - I/O events dispatcher.

HashTable - hash table creation and search.

OptionsScan - command-line options scanning.

Endpoint - network endpoint.

TcpEndpoint - TCP/IP endpoint.

BufferedTCP - buffered TCP/IP stream.

CortexStream - CORTEX network stream.

Applications

anise

A pocket FTP/WWW server.

finc

Networking extensions to John Sadler's Ficl (Forth Inspired Command Language) interpreter.

gentle

A network server that provides each client with its own Tcl interpreter, extended with networking and hardware debugging commands. (Derived from earlier programs, nicl and picl!)

npath

Collects function-by-function metrics for C source code. The metrics include lines-of-code, Halstead's Software Science volume, McCabe's cyclomatic complexity, and NPATH.

tsion

Networking extensions to the TinyScheme interpreter.

Generic Tools

chafn - change file names.

colior - dump CORBA Interoperable Object Reference (IOR).

dump - formatted dump program.

duop - dump Opera files.

ffc - format file in columns.

gflow - graph flow.

talknet - network talk utility.

tag311 - add/change ID3v1.1 tags on MP3 files.

Project-Specific Tools (EPOCH)

	cdc - EPOCH CORBA command database client.
	const - EPOCH V3 node management client.
	cornet - CORTEX network tool.
	dart - EPOCH CORBA data retriever client.
	db4u - EPOCH CORBA telemetry database client.
	direct - EPOCH V3 directive submitter.
	dirt - EPOCH CORBA directive submitter.
	dssi - Dynamic Spacecraft Simulator (DSS) Interface client or server.
	dumpaev - EPOCH archive dumper.
	eire - EPOCH V3 events reader.
	eniac - Enertec interactive client.
	epcot - EPOCH-CORTEX telemetry server.
	f4rd - EPOCH CORBA telemetry frame reader.
	glop - EPOCH V3 global variable print.
	mcci - acts as a Mission Control Center (MCC) client or Spacecraft Control Center (SCC) server.
	milk - EPOCH device handler reader/writer.
	noman - EPOCH CORBA node management client.
	psic - EPOCH CORBA telemetry point service client.
	stamp - EPOCH V3 stored command client.
	v3net - generic EPOCH client/server network tool.
	v4ever - EPOCH CORBA events reader.