next up previous contents
Next: Problem solving Up: LibClamAV Previous: LibClamAV   Contents

API

Each program using libclamav must include clamav.h header file:
	#include <clamav.h>
The first step is an engine initialization. There are three functions available:
	int cl_loaddb(const char *filename, struct cl_node **root,
	int *virnum);

	int cl_loaddbdir(const char *dirname, struct cl_node **root,
	int *virnum);

	char *cl_retdbdir(void);
cl_loaddb() loads one database per time, cl_loaddbdir() loads all .db and .db2 files from the directory dirname. cl_retdbdir() returns hardcoded database directory path. The database will be saved under root and the number of the loaded signatures will be added to virnum. Pointer to the tree structure (trie, see 7.2) must initially point to the NULL. If you don't want to save the number of signatures loaded pass the NULL as the third argument. cl_loaddb functions return 0 on success and other value on failure.
	    struct cl_node *root = NULL;
	    int ret;

	ret = cl_loaddbdir(cl_retdbdir(), &root, NULL);
There's elegant way to print libclamav's error codes:
	char *cl_perror(int clerror);
cl_perror() returns a (statically allocated) string describing clerror code:
	if(ret) {
	    printf("cl_loaddbdir() error: %s\n", cl_perror(ret));
	    exit(1);
	}
When database is loaded, you must create the proper trie with:
	void cl_buildtrie(struct cl_node *root);
In our example:
	cl_buildtrie(root);
OK, now you can scan a buffer, descriptor or file with:
	int cl_scanbuff(const char *buffer, unsigned int length,
	char **virname, const struct cl_node *root);

	int cl_scandesc(int desc, char **virname, unsigned long int
	*scanned, const struct cl_node *root, const struct cl_limits
	*limits, int options);

	int cl_scanfile(const char *filename, char **virname,
	unsigned long int *scanned, const struct cl_node *root,
	const struct cl_limits *limits, int options);
All the functions save a virus name address under virname pointer. virname points to the name in the trie structure, thus it can't be released directly. cl_scandesc() and cl_scanfile() can increase scanned value in CL_COUNT_PRECISION units. They also support archive limits:
	struct cl_limits {
	    int maxreclevel;
	    int maxfiles;
	    long int maxfilesize;
	};
The last argument configures scan engine. Currently it supports CL_ARCHIVE (enables archive scanning), CL_RAW (disables archive scanning) and CL_MAIL (enables mbox and Maildir scanning). The functions return 0 (CL_CLEAN) when no virus is found, CL_VIRUS when virus is found and other value on failure.
	    struct cl_limits limits;
	    char *virname;

	/* maximal number of files in archive */;
	limits.maxfiles = 100
	/* maximal archived file size == 10 Mb */
	limits.maxfilesize = 10 * 1048576;
	/* maximal recursion level */
	limits.maxreclevel = 8;


	if((ret = cl_scanfile("/home/zolw/test", &virname, NULL, root,
	&limits, CL_ARCHIVE)) == CL_VIRUS) {
	    printf("Detected %s virus.\n", virname);
	} else {
	    printf("No virus detected.\n");
	    if(ret != CL_CLEAN)
	        printf("Error: %s\n", cl_perror(ret));
	}
When you don't need to scan more files, the trie should be released with:
	void cl_freetrie(struct cl_node *root);
You will find some examples in clamav sources. Each program using libclamav must be linked against it:
	gcc -Wall ex1.c -o ex1 -lclamav
Enjoy !


next up previous contents
Next: Problem solving Up: LibClamAV Previous: LibClamAV   Contents
Tomasz Kojm 2003-06-21