Data scan functions

It's possible to scan a buffer, a descriptor, or a file with:

	int cl_scanbuff(const char *buffer, unsigned int length,
	const char **virname, const struct cl_node *root);

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

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

All the functions save a virus name under virname pointer. It points to a field in the internal database structure and must not be released directly. If the scanned pointer is not NULL the functions will increase a value represented by this pointer by a size of scanned data in CL_COUNT_PRECISION units. The last two functions also support archive limits required to protect against Denial of Service attacks.

	struct cl_limits {
	    int maxreclevel; /* maximal recursion level */
	    int maxfiles; /* maximal number of files to be
                   * scanned within archive
                   */
	    int maxratio; /* maximal compression ratio */
	    short archivememlim; /* limit memory usage for bzip2 (0/1) */
	    long int maxfilesize; /* archived files larger than this
                           * value will not be scanned
                           */
	};

The options argument configures the scan engine and supports the following flags (that can be combined using bit operators):

• CL_SCAN_STDOPT
  This is an alias for a recommended set of scan options. You should use it to make your software ready for new features in future versions of libclamav.
• CL_SCAN_RAW
  It does nothing. Please use it (alone) if you don't want to scan any special files.
• CL_SCAN_ARCHIVE
  This flag enables transparent scanning of various archive formats.
• CL_SCAN_BLOCKENCRYPTED
  With this flag the library marks encrypted archives as viruses (Encrypted.Zip, Encrypted.RAR).
• CL_SCAN_BLOCKMAX
  Mark archives as viruses if maxfiles, maxfilesize, or maxreclevel limit is reached.
• CL_SCAN_MAIL
  It enables support for mail files.
• CL_SCAN_MAILURL
  The mail scanner will download and scan URLs listed in a mail body. This flag should not be used on loaded servers. Due to potential problems please do not enable it by default but make it optional.
• CL_SCAN_OLE2
  Enables support for Microsoft Office document files.
• CL_SCAN_PE
  This flag enables scanning withing Portable Executable files and allows libclamav to unpack UPX, Petite, and FSG compressed executables.
• CL_SCAN_BLOCKBROKEN
  libclamav will try to detect broken executables and mark them as Broken.Executable.
• CL_SCAN_HTML
  This flag enables HTML normalisation (including JScript decryption).

All functions return 0 (CL_CLEAN) if the file is clean, CL_VIRUS when virus is detected and an another value on failure.

	    ...
	    struct cl_limits limits;
	    const char *virname;

	memset(&limits, 0, sizeof(struct cl_limits));
	/* maximal number of files in archive */;
	limits.maxfiles = 1000
	/* maximal archived file size */
	limits.maxfilesize = 10 * 1048576; /* 10 MB */
	/* maximal recursion level */
	limits.maxreclevel = 5;
	/* maximal compression ratio */
	limits.maxratio = 200;
	/* disable memory limit for bzip2 scanner */
	limits.archivememlim = 0;

	if((ret = cl_scanfile("/home/zolw/test", &virname, NULL, root,
	&limits, CL_STDOPT)) == CL_VIRUS) {
	    printf("Detected %s virus.\n", virname);
	} else {
	    printf("No virus detected.\n");
	    if(ret != CL_CLEAN)
	        printf("Error: %s\n", cl_strerror(ret));
	}