libnetmar - The Netmar C Library
PURPOSE
WELCOME! The functions documented below and on the attached
pages represent the bulk of the programming work that we've saved over our years
of operation here at Netmar. As any good C programmer is taught to do, we have
saved the more flexible functions from all the software we've written so that
future programs we write could be implemented more quickly and easily and without
reinventing the wheel every time.
As these functions have helped us tremendously in writing new programs over
the years, we hope they will help you too. So, we've taken the unprecedented
step of making these functions available to you, our customers, for use in your
own programs, as a complete C library. And while we can't release the full source
code of the library, we have created a standard C archive library to which you
can link your C programs upon compilation to use any of these functions.
USAGE
To use libnetmar, you need to do only two things:
- Insert an include for the netmar.h header file in each of your C source
files that references one of the libnetmar functions
(e.g. "#include <netmar.h>"), and
- Link your program with -lnetmar upon compilation
(e.g. gcc -o myprogram myprogram.c -lnetmar)
That's it! You can then use any of the functions in libnetmar in your C programs
and CGI scripts.
TESTING & SUPPORT
All of the functions in libnetmar have been independently tested (outside of
the program for which they were designed) and then used successfully in a program.
So, while we can't guarantee the entire library is bug free, we do know that
all of these functions work because they have all been tested and used ina real
life environment.
If, however, you find something that you think is a bug, we would be appreciative
if you would point it out to us, and tell us in as much detail as possible,
how you came upon it. If ths situation caused your program to crash, we would
appreciate you saving a core file for us. You can do this by typing "limit
coredumpsize unlimited" at the command prompt before running the
program. Please note that if your program is a CGI script, you can still run
it from the command line to debug it by using the cgi_assign or getcgidata functions
from the library.
As these function were written by us and are being made available to our customers
as part of the webhosting service we offer, Netmar provides full technical support
for users of the library. However, please note that Netmar technical support
does not offer tutoring or support for the C programming language itself. If
you don't understand how to write or compile your program, please consult your
reference materials.
CGI Section
This section contains functions for use in writing CGI scripts. If you're writing
a script, you want to use assign (with getcgidata) or cgi_assign as these fully
automate the input task while also including a debugging interface. These function
calls, together with fsend or tfsend, reduce the I/O portions of code in a CGI
program to as little as two lines (one function call to read input, and one to
send all output).
Other functions allow you to do some more advanced tasks, like sending your
data to another CGI script via a POST request and encoding/decoding HTML and
URL encoded strings.
If you're writing a CGI script, you'll also want to see the tfsend
function in the next section.
- assign-
Assign CGI variable data directly to C variables from an existing data structure.
- cgi- Get data
from CGI or simulated input.
- cgi_assign-
Assign CGI variable data directly to C variables directly from the CGI input
data.
- checked-
Retrieve checkbox information from a standard format CGI data output file.
- getcgidata-
Automatically get data from the appropriate type of CGI or simulated input.
- getgetdata-
Get data input via a HTTP GET request for a CGI script.
- getmockdata-
Get data input via keyboard and return it in the same form as CGI data.
- getpostdata-
Get data input via a HTTP POST request for a CGI script.
- getval-
Retrieve variable information from a standard format CGI data output file.
- header-
Determine if a line in a standard format CGI data output file contains a variable
name and header.
- htencode-
HTML encode a string (by escaping <, >, &, and " characters)
- htpost-
Send a POST data body to an HTTP server via a POST request, returning the
results to open file pointers.
- htpost_s-
Send a POST data body to an HTTP server via a POST request, returning the
results to character array pointers.
- makepost-
Construct a POST data body.
- repost-
Send an existing CGI data structure to an HTTP server as a POST data body.
- unescape_url-
Unescape a string containing URL escaped characters.
- urlencode-
Encode a string by URL escaping certain characters.
Data Handling Section
The functions in this section provide various methods for reading, writing, and
manipulating data. Mostly, these functions serve as shortcuts for what would otherwise
be oft-typed repetitive code in a program. With the exception of the fsend, tfsend,
and pgp_enc functions, these functions are mostly just shortcuts.
- database-
dbm, ndbm, and gdbm database interface routines
- dbfget-
retrieve an float from a dbm, ndbm, or gdbm database
- dbfstore-
store a float in a dbm, ndbm, or gdbm database
- dbiget-
retrieve an integer from a dbm, ndbm, or gdbm database
- dbistore-
store an integer in a dbm, ndbm, or gdbm database
- dblget-
retrieve an long integer from a dbm, ndbm, or gdbm database
- dblstore-
store a long integer in a dbm, ndbm, or gdbm database
- dbsget-
retrieve a string rom a dbm, ndbm, or gdbm database
- dbsstore-
store a string in a dbm, ndbm, or gdbm database
- fsend- Parse
and output a file using ordinal subcodes
- grep- Search
through lines of text
- imakedatum-
Convert an integer into data type datum suitable for storage in a database
- makedatum-
Convert data into data type datum suitable for storage in a database
- makekey-
Make a key for storing data in a dbm, ndbm, or gdbm database
- pgp_enc-
Encrypt a string using PGP
- smakedatum-
Convert a string into data type datum suitable for storage in a database
- tfsend-
Parse and output a file using nominal substitution codes (for CGI output mainly)
Miniature Tools Section
This section consists of functions that do various sundry tasks that could just
be made easier and reusable by creating a separate function. So we did. Nothing
here is earth-shattering. The things accomplished by these functions could be
done by most programmers, regardless of level, but would just take time to code.
So these functions are mainly just for convenience. You'll notice that some are
for some very specific tasks. These are tasks that we needed to accomplish in
writing certain program. The usefulness of some of these functions outside of
the programs for which they were written is probably questionable. But the functions
were already written, so we're including them in this secion.
- cat- Output
a file to stdout
- dconvert-
Convert the day number into a date for this year
- fcat- Output
a file to a file pointer
- getname-
Retrieve the full name of a user from the system password file
- gettime-
convert minutes and seconds portion of HTTP log format time string to integer
- itoa- Convert
integer to string without using sprintf()
- itoh- Convert
integer to string showing hexadecimal value without using sprintf()
- minfo- Show
mallinfo() (memory arena) information (Solaris only)
- rnd- Generate
random integers
- rprintf-
Pad output with spaces
- seconds-
Convert seconds to minutes and seconds
- tail- Show
trailing lines of a file (with no limit)
- wdwrap-
Wrap lines of a text file
- whois_check-
Check for domain name availability of InterNIC-delegated domains
- xwdwrap-
Wrap lines of a text file at any length and check for solid lines
Miscellaneous Tools Section
This section also contains functions that are mostly for convenience (providing
simple functionality). But these functions are more likely to be of interest to
programmers for use in more programs as the functionality provided is more commonly
needed in CGI and Unix programming.
- authenticate-
Authenticate login/password against a Unix/htpasswd style password file
- ccard_valid-
Determine if a supplied credit card number could be a valid card number
- cdate- Convert
a date string from one format to another
- crstrip-
Strip trailing CR and LF characters from a string
- domcheck-
Determine if a string is a properly formatted domain name (no validity check)
- emailcheck-
Determine if a string is a properly formatted email address (no validity check)
- envcpy-
Copy current environment to a string for use with the env command
- fphd2user-
Determine user in whose home directory a filepath resides (read from fp)
- hd2user-
Determine user in whose home directory a filepath resides
- ishost-
Determine if a string is a properly formatted hostname (no validity check)
- isweb- Determine
if a string is a properly formatted WWW URL (no validity check)
Network Section
Network programming traditionally has required a platform specific level of understanding
that is often beyond most novice programmers and even many intermediate and advanced
programmers. It is almost always well beyond a programmers that is new to the
platform. So, we have saved as separate functions, the code we have used in the
past to communicate over TCP/IP sockets.
There are two sets of functions here. One is a medium level interface, which
provides direct interaction with the TCP/IP socket with no buffering, while
the other, a high level interfare, provides a buffered, error-controlled, and
timed interface almost exactly identical to the file I/O interface provided
by the stdio functions fgets and fputs.
- call- Initiate
a TCP/IP connection to the given host and port (high-level interface)
- callsock-
Initiate a TCP/IP connection to the given host and port (medium-level interface)
- sgets- Get
a string from the given TCP/IP session (medium-level interface)
- sockclose-
Close a TCP/IP connection (high-level interface)
- socket-
Medium level interface to TCP/IP sockets
- sockgets-
Get a string from the given TCP/IP session (high-level interface)
- sockputs-
Write a line to a TCP/IP connection (high-level interface)
- sread- Read
data from a TCP/IP connection (medium-level interface)
- swrite-
Write data to a TCP/IP connection (medium-level interface)
- tcputil-
High leve interface to TCP/IP sockets
String Tools Section
It has often been said that one of the main advantages of Perl over C is the ease
of string manipulation built into the Perl language. The functions in this section
provide a higher level of control over strings than that provided by the ANSI
C string.h functions.
- ccut- Cut
text by column number (like /usr/bin/cut -c)
- comma- Convert
integer to string with commas for numbers over 1,000
- fcount-
Count number of fields in a string separated by a given separator character
- fcut- Cut
text by field (like /usr/bin/cut -d)
- mfcut- Cut
multiple fields of text (like /usr/bin/cut -d)
- strcaseconv-
Convert string case to all upper or all lower
- strcasestr-
Case insensitive string search (like strstr)
- strip- Strip
leading and/or trailing repeptitive characters
- subst- Search
and replace text in a string
- xsubst-
Search and replace text in a string globally or one per string
