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