Next: Memory Up: Database reloading Previous: Database reloading Contents

### 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));
    	}

Next: Memory Up: Database reloading Previous: Database reloading Contents