NAME

catutils - utility functions

DESCRIPTION

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.

FUNCTION OVERVIEW

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.

SEE ALSO

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