In a multi-threaded program only the main thread must call yr_initialize() and yr_finalize(). No additional work is required from other threads using the library.
The yr_compiler_add_file(), yr_compiler_add_fd(), and yr_compiler_add_string() functions return the number of errors found in the source code. If the rules are correct they will return 0. If any of these functions return an error the compiler can’t used anymore, neither for adding more rules nor getting the compiled rules.
By default, for rules containing references to other files (include "filename.yara"), YARA will try to find those files on disk. However, if you want to fetch the imported rules from another source (eg: from a database or remote service), a callback function can be set with yr_compiler_set_include_callback().
include_name: name of the requested file.
calling_rule_filename: the requesting file name (NULL if not a file).
calling_rule_namespace: namespace (NULL if undefined).
user_data pointer is the same you passed to yr_compiler_set_include_callback().
It should return the requested file’s content as a null-terminated string. The memory for this string should be allocated by the callback function. Once it is safe to free the memory used to return the callback’s result, the include_free function passed to yr_compiler_set_include_callback() will be called. If the memory does not need to be freed, NULL can be passed as include_free instead. You can completely disable support for includes by setting a NULL callback function with yr_compiler_set_include_callback().
If your rules make use of external variables (like in the example below), you must define those variables by using any of the yr_compiler_define_XXXX_variable functions. Variables must be defined before rules are compiled with yr_compiler_add_XXXX and they must be defined with a type that matches the context in which the variable is used in the rule, a variable that is used like my_var == 5 can’t be defined as a string variable.
While defining external variables with yr_compiler_define_XXXX_variable you must provide a value for each variable. That value is embedded in the compiled rules and used whenever the variable appears in a rule. However, you can change the value associated to an external variable after the rules has been compiled by using any of the yr_rules_define_XXXX_variable functions.
The ptr argument is a pointer to the buffer where the read function should put the read data, or where the write function will find the data that needs to be written to the stream. In both cases size is the size of each element being read or written and count the number of elements. The total size of the data being read or written is size * count. The read function must return the number of elements read, the write function must return the total number of elements written.
Once you have an instance of YR_RULES you can use it directly with one of the yr_rules_scan_XXXX functions described below, or create a scanner with yr_scanner_create(). Let’s start by discussing the first approach.
Notice that you shouldn’t call any of the yr_rules_scan_XXXX functions from within the callback as those functions are not re-entrant.
The yr_rules_scan_XXXX functions are enough in most cases, but sometimes you may need a fine-grained control over the scanning. In those cases you can create a scanner with yr_scanner_create(). A scanner is simply a wrapper around a YR_RULES structure that holds additional configuration like external variables without affecting other users of the YR_RULES structure.
A scanner is particularly useful when you want to use the same YR_RULES with multiple workers (it could be a separate thread, a coroutine, etc) and each worker needs to set different set of values for external variables. In that case you can’t use yr_rules_define_XXXX_variable for setting the values of your external variables, as every worker using the YR_RULES will be affected by such changes. However each worker can have its own scanner, where the scanners share the same YR_RULES, and use yr_scanner_define_XXXX_variable for setting external variables without affecting the rest of the workers.
This is a better solution than having a separate YR_RULES for each worker, as YR_RULES structures have large memory footprint (specially if you have a lot of rules) while scanners are very lightweight.
Any thread using the library, except the main thread, must call this function when it finishes using the library. Since version 3.8.0 this calling this function is not required anymore, and it’s deprecated.
New in version 3.7.0: Set a callback to provide rules from a custom source when include directive is invoked. The user_data pointer is untouched and passed back to the callback function and to the free function. Once the callback’s result is no longer needed, the include_free function will be called. If the memory does not need to be freed, include_free can be set to NULL. If callback is set to NULL support for include directives is disabled.
Define an integer external variable.
Define a float external variable.
Define a boolean external variable.
Define a string external variable.
Disable the specified rule. Disabled rules are completely ignored during the scanning process and they won’t match. If the disabled rule is used in the condition of some other rule the value for the disabled rule is neither true nor false but undefined. For more information about undefined values see Undefined values.
Enables the specified rule. After being disabled with yr_rule_disable() a rule can be enabled again by using this function.
Destroy a scanner. After using a scanner it must be destroyed with this function.
Set a callback function that will be called for reporting any matches found by the scanner.
Set the maximum number of seconds that the scanner will spend in any call to yr_scanner_scan_xxx .
Set the flags that will be used by any call to yr_scanner_scan_xxx .