catutils - utility functions
The catutils module is a collection of ``convenience functions'' that are used in
different parts of the Agent SDK.
Most utility functions are related to another module of the API.
- Data conversion
-
These routines are used to convert between different character encodings.
This is particularly useful for UAR data since UARs are coded in UTF-8
(backwards compatible with 7-bit ASCII). These functions can be used to
convert to native wide characters or latin1.
- Thread synchronization
-
The SDK provides a set of portable macros that implement a few basic
synchronization primitives with the same semantics on all platforms. These
should be used to protect any shared global data.
- Hostname and service lookup
-
These functions perform hostname and service lookups. The functions are
thread-safe, unlike the native versions. They also return data in string
form and behave in the same way on all platforms.
The structures used are defined as follows:
typedef struct catnet_host {
char **names; /* name, alias, ..., NULL */
char **addrs; /* addresses, as strings, NULL-terminated */
} catnet_host;
typedef struct catnet_serv {
char **names; /* name, alias, ..., NULL */
int port; /* port number */
} catnet_serv;
These functions are related to the catnet module.
- File utilities
-
A number of miscellaneous functions are provided. These include functions
for file locking and functions to get file status.
- Cache databases
-
Various protocol functions can make use of a user-supplied cache manager.
The Agent SDK provides two of these functions, one in-memory, and one
on-disk.
- cat_base64tobin
-
Transform Base64 encoded data to binary data.
- cat_bintobase64
-
Transform binary data to Base64 encoded data.
- cat_getfile
-
Read a file into memory from disk if the file is available.
- cat_latin1toutf
-
Transform latin1 encoded characters to UTF encoding.
- cat_utftolatin1
-
Transform UTF8 encoded characters to latin1 encoding.
- cat_needutf
-
Check if an ASCII string needs further processing in order for it to have a
valid UTF-8 format.
- cat_utftowc
-
Transform UTF-8 encoded characters to wide characters.
- cat_wctoutf
-
Transform wide characters to UTF-8 encoding.
- cat_sleep
-
Suspend a calling thread for a number of seconds.
- cat_fork
-
cat_fork() is a wrapper function for the standard fork() function on UNIX platforms.
- catmutex_cond_free
-
Delete a condition variable when using threads.
- catmutex_cond_init
-
Initialize a condition variable when using threads.
- catmutex_cond_signal
-
Signal a condition variable to wake up any threads sleeping on the
condition variable.
- catmutex_cond_wait
-
Make a thread go to sleep on a condition variable.
- catmutex_free
-
This function deletes initialized mutex m. The mutex must not be held when this function is called.
- catmutex_init
-
Initialize a thread mutex.
- catmutex_lock
-
Lock a thread mutex.
- catmutex_unlock
-
Unlock a mutex that has been locked by catmutex_lock().
- catthread_equal
-
Compare two thread identifiers to see if they are equal, that is, the same
thread.
- catthread_self
-
Get the thread ID for the calling thread.
- catthread_start
-
Create a new thread and start execution in the supplied function.
- cat_hostname
-
Return the hostname of the local host.
- catnet_hostbyaddr
-
Take a given name as an IP address in dotted-decimal form (as returned by catnet_getnetinfo()), and return the corresponding list of names and addresses, as identified
by the naming service (for example, DNS) in use on the machine.
- catnet_hostbyname
-
Take a given name as a host name or an IP address in dotted-decimal form (as returned by catnet_getnetinfo()), and return the corresponding list of names and addresses, as identified
by the naming service (for example, DNS) in use on the machine.
- catnet_servbyname
-
A thread-safe wrapper function used to retrieve the service via the service
name and the protocol.
- catnet_servbyport
-
A thread safe wrapper function used to retrieve the service via the service port number and the protocol.
- cat_filelength
-
Retrieve the size of a file on disk.
- cat_filetime
-
Return the time when a file was last modified.
- cat_lockfile
-
Lock an open, writeable file.
- cat_unlockfile
-
Unlock a previously locked file.
- cat_truncatefile
-
Set the length of an open, writeable file on disk.
- cat_newmemdb
-
Create an in-memory database that can be used, for example, as a cache. The
catinfo tree is created using this function.
- cat_freememdb
-
Release an in-memory database function and destroy its contents.
- cat_memdbflags
-
Change the behavior of cat_memdb functions.
- cat_memdbforeach
-
Traverse an in-memory database and apply a supplied callback to all
entries.
- cat_memdbfunc
-
Perform an operation on an element in an in-memory database.
- cat_newfiledb
-
Create a database on disk (UNIX only).
- cat_filedbfunc
-
Perform an operation on an element in a database in a file on disk.
- cat_freefiledb
-
Destroy a file database and its contents.
cat, catnet
cat_base64tobin,
cat_bintobase64, cat_getfile, cat_latin1toutf,
cat_needutf, cat_utftolatin1, cat_utftowc, cat_wctoutf
cat_sleep, cat_fork
catmutex_cond_free, catmutex_cond_init, catmutex_cond_signal,
catmutex_cond_wait, catmutex_free, catmutex_init,
catmutex_lock, catmutex_unlock, catthread_equal,
catthread_self, catthread_start
cat_hostname, catnet_hostbyaddr, catnet_hostbyname,
catnet_servbyname, catnet_servbyport
cat_filelength, cat_filetime, cat_lockfile,
cat_truncatefile, cat_unlockfile, cat_filedbfunc, cat_newfiledb,
cat_freefiledb
cat_freememdb, cat_memdbflags, cat_memdbforeach,
cat_memdbfunc, cat_newmemdb