Keywords: clamdoc

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

### Data scan functions

It's possible to scan a file or descriptor using:

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

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

Both functions will save a virus name under the pointer `virname`, the virus name is part of the engine structure and must not be released directly. If the third argument (`scanned`) is not NULL, the functions will increase its value with the size of scanned data (in `CL_COUNT_PRECISION` units). Both functions have support for archive limits in order to protect against Denial of Service attacks.

    struct cl_limits {
        unsigned int maxreclevel;     /* maximum recursion level for archives */
        unsigned int maxfiles;        /* maximum number of files to be scanned
                                       * within a single archive
                                       */
        unsigned int maxmailrec;	  /* maximum recursion level for mail files */
        unsigned int maxratio;	  /* maximum compression ratio */
        unsigned long int maxfilesize;/* compressed files larger than this limit
                                       * will not be scanned
                                       */
        unsigned short archivememlim;  /* limit memory usage for some unpackers */
    };

The last argument (`options`) 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 the future versions of libclamav.
- CL_SCAN_RAW
  Use it alone if you want to disable support for special files.
- CL_SCAN_ARCHIVE
  This flag enables transparent scanning of various archive formats.
- CL_SCAN_BLOCKENCRYPTED
  With this flag the library will mark 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
  Enable 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 OLE2 containers (used by MS Office and .msi files).
- CL_SCAN_PDF
  Enables scanning within PDF files.
- CL_SCAN_PE
  This flag enables deep scanning of Portable Executable files and allows libclamav to unpack executables compressed with run-time unpackers.
- CL_SCAN_ELF
  Enable support for ELF files.
- 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 ScrEnc decryption).
- CL_SCAN_ALGORITHMIC
  Enable algorithmic detection of viruses.
- CL_SCAN_PHISHING_DOMAINLIST
  Phishing module: restrict URL scanning to domains from .pdf (RECOMMENDED).
- CL_SCAN_PHISHING_BLOCKSSL
  Phishing module: always block SSL mismatches in URLs.
- CL_SCAN_PHISHING_BLOCKCLOAK
  Phishing module: always block cloaked URLs.

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

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

    	memset(&limits, 0, sizeof(struct cl_limits));
    	limits.maxfiles = 1000; /* max files */
    	limits.maxfilesize = 10 * 1048576; /* maximum size of archived or
                                        * compressed file (files exceeding
                                        * this limit will be ignored)
                                        */
    	limits.maxreclevel = 5; /* maximum recursion level for archives */
    	limits.maxmailrec = 64; /* maximum recursion level for mail files */
    	limits.maxratio = 200; /* maximum compression ratio */

    	if((ret = cl_scanfile("/tmp/test.exe", &virname, NULL, engine,
    	&limits, CL_STDOPT)) == CL_VIRUS) {
    	    printf("Virus detected: %s\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