--- name: "Uil" section: "3" platform: "linux" package: "openmotif" version: "2.3.8-4" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Uil" --- # Uil(3) Invokes the UIL compiler from within an application ## NAME **Uil** — Invokes the UIL compiler from within an application ## SYNOPSIS ``` #include Uil_status_type Uil( Uil_command_type *command_desc, Uil_compile_desc_type **compile_desc, Uil_continue_type (*message_cb) (), char *message_data, Uil_continue_type (*status_cb) (), char *status_data); ``` ## DESCRIPTION The **Uil** function provides a callable entry point for the UIL compiler. The **Uil** callable interface can be used to process a UIL source file and to generate UID files, as well as return a detailed description of the UIL source module in the form of a symbol table (parse tree). - *command\_desc* Specifies the **uil** command line. - *compile\_desc* Returns the results of the compilation. - *message\_cb* Specifies a callback function that is called when the compiler encounters errors in the UIL source. - *message\_data* Specifies user data that is passed to the message callback function (*message\_cb)*. Note that this argument is not interpreted by UIL, and is used exclusively by the calling application. - *status\_cb* Specifies a callback function that is called to allow X applications to service X events such as updating the screen. This function is called at various check points, which have been hard coded into the UIL compiler. The *status\_update\_delay* argument in *command\_desc* specifies the number of check points to be passed before the *status\_cb* function is invoked. - *status\_data* Specifies user data that is passed to the status callback function (*status\_cb).* Note that this argument is not interpreted by the UIL compiler and is used exclusively by the calling application. Following are the data structures **Uil\_command\_type** and **Uil\_compile\_desc\_type**: ``` typedef struct Uil_command_type { char *source_file; /* single source to compile */ char *resource_file; /* name of output file */ char *listing_file; /* name of listing file */ unsigned int *include_dir_count; /* number of dirs. in include_dir */ char *((*include_dir) []); /* dir. to search for include files */ unsigned listing_file_flag: 1; /* produce a listing */ unsigned resource_file_flag: 1; /* generate UID output */ unsigned machine_code_flag: 1; /* generate machine code */ unsigned report_info_msg_flag: 1; /* report info messages */ unsigned report_warn_msg_flag: 1; /* report warnings */ unsigned parse_tree_flag: 1; /* generate parse tree */ unsigned int status_update_delay; /* number of times a status point is */ /* passed before calling status_cb */ /* function 0 means called every time */ char *database; /* name of database file */ unsigned database_flag: 1; /* read a new database file */ unsigned use_setlocale_flag: 1; /* enable calls to setlocale */ }; typedef struct Uil_compile_desc_type { unsigned int compiler_version; /* version number of compiler */ unsigned int data_version; /* version number of structures */ char *parse_tree_root; /* parse tree output */ unsigned int message_count [Uil_k_max_status+1]; /* array of severity counts */ }; ``` Following is a description of the message callback function specified by *message\_cb*: ``` Uil_continue_type (*message_cb) (message_data, message_number, severity, msg_buffer, src_buffer, ptr_buffer, loc_buffer, message_count) char *message_data; int message_number; int severity; char *msg_buffer, *src_buffer; char *ptr_buffer, *loc_buffer; int message_count[]; ``` This function specifies a callback function that UIL invokes instead of printing an error message when the compiler encounters an error in the UIL source. The callback should return one of the following values: - **Uil\_k\_terminate** Terminate processing of the source file - **Uil\_k\_continue** Continue processing the source file The arguments are - *message\_data* Data supplied by the application as the *message\_data* argument to the **Uil** function. UIL does not interpret this data in any way; it just passes it to the callback. - *message\_number* An index into a table of error messages and severities for internal use by UIL. - *severity* An integer that indicates the severity of the error. The possible values are the status constants returned by the **Uil** function. See **Return Value** for more information. - *msg\_buffer* A string that describes the error. - *src\_buffer* A string consisting of the source line where the error occurred. This string is not always available. In this case, the argument is NULL. - *ptr\_buffer* A string consisting of whitespace and a printing character in the character position corresponding to the column of the source line where the error occurred. This string may be printed beneath the source line to provide a visual indication of the column where the error occurred. This string is not always available. In this case, the argument is NULL. - *loc\_buffer* A string identifying the line number and file of the source line where the error occurred. This is not always available; the argument is then NULL. - *message\_count* An array of integers containing the number of diagnostic messages issued thus far for each severity level. To find the number of messages issued for the current severity level, use the *severity* argument as the index into this array. Following is a description of the status callback function specified by *status\_cb*: ``` Uil_continue_type (*status_cb) (status_data, percent_complete, lines_processed, current_file, message_count) char *status_data; int percent_complete; int lines_processed; char *current_file; int message_count[]; ``` This function specifies a callback function that is invoked to allow X applications to service X events such as updating the screen. The callback should return one of the following values: - **Uil\_k\_terminate** Terminate processing of the source file - **Uil\_k\_continue** Continue processing the source file The arguments are - *status\_data* Data supplied by the application as the *status\_data* argument to the **Uil** function. UIL does not interpret this data in any way; it just passes it to the callback. - *percent\_complete* An integer indicating what percentage of the current source file has been processed so far. - *lines\_processed* An integer indicating how many lines of the current source file have been read so far. - *current\_file* A string containing the pathname of the current source file. - *message\_count* An array of integers containing the number of diagnostic messages issued thus far for each severity level. To find the number of messages issued for a given severity level, use the severity level as the index into this array. The possible severity levels are the status constants returned by the **Uil** function. See **Return Value** for more information. ## RETURN This function returns one of the following status return constants: - **Uil\_k\_success\_status** The operation succeeded. - **Uil\_k\_info\_status** The operation succeeded. An informational message is returned. - **Uil\_k\_warning\_status** The operation succeeded. A warning message is returned. - **Uil\_k\_error\_status** The operation failed due to an error. - **Uil\_k\_severe\_status** The operation failed due to an error. ## RELATED [**UilDumpSymbolTable**(3)](/UilDumpSymbolTable/3.md) and [**uil**(1)](/uil/1.md).