Keywords: clamdoc

### 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 store 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 long int maxscansize;  /* during the scanning of archives this
                                         * size will never be exceeded
                                         */
        unsigned long int maxfilesize;  /* compressed files will only be
                                         * decompressed and scanned up to this size
                                         */
        unsigned int maxreclevel;       /* maximum recursion level for archives */
        unsigned int maxfiles;          /* maximum number of files to be scanned
                                         * within a single archive
                                         */
        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_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_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 = 10000;
    	limits.maxscansize = 100 * 1048576; /* 100 MB */
    	limits.maxfilesize = 10 * 1048576; /* 10 MB */
    	limits.maxreclevel = 16;

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