| /* |
| * gawkapi.h -- Definitions for use by extension functions calling into gawk. |
| */ |
| |
| /* |
| * Copyright (C) 2012, 2013 the Free Software Foundation, Inc. |
| * |
| * This file is part of GAWK, the GNU implementation of the |
| * AWK Programming Language. |
| * |
| * GAWK is free software; you can redistribute it and/or modify |
| * it under the terms of the GNU General Public License as published by |
| * the Free Software Foundation; either version 3 of the License, or |
| * (at your option) any later version. |
| * |
| * GAWK is distributed in the hope that it will be useful, |
| * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| * GNU General Public License for more details. |
| * |
| * You should have received a copy of the GNU General Public License |
| * along with this program; if not, write to the Free Software |
| * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA |
| */ |
| |
| /* |
| * The following types and/or macros and/or functions are referenced |
| * in this file. For correct use, you must therefore include the |
| * corresponding standard header file BEFORE including this file. |
| * |
| * FILE - <stdio.h> |
| * NULL - <stddef.h> |
| * malloc() - <stdlib.h> |
| * memset(), memcpy() - <string.h> |
| * size_t - <sys/types.h> |
| * struct stat - <sys/stat.h> |
| * |
| * Due to portability concerns, especially to systems that are not |
| * fully standards-compliant, it is your responsibility to include |
| * the correct files in the correct way. This requirement is necessary |
| * in order to keep this file clean, instead of becoming a portability |
| * hodge-podge as can be seen in the gawk source code. |
| * |
| * To pass reasonable integer values for ERRNO, you will also need to |
| * include <errno.h>. |
| */ |
| |
| #ifndef _GAWK_API_H |
| #define _GAWK_API_H |
| |
| /* |
| * General introduction: |
| * |
| * This API purposely restricts itself to ISO C 90 features. In particular, no |
| * bool, no // comments, no use of the restrict keyword, or anything else, |
| * in order to provide maximal portability. |
| * |
| * Exception: the "inline" keyword is used below in the "constructor" |
| * functions. If your compiler doesn't support it, you should either |
| * -Dinline='' on your command line, or use the autotools and include a |
| * config.h in your extensions. |
| * |
| * Additional important information: |
| * |
| * 1. ALL string values in awk_value_t objects need to come from malloc(). |
| * Gawk will handle releasing the storage if necessary. This is slightly |
| * awkward, in that you can't take an awk_value_t that you got from gawk |
| * and reuse it directly, even for something that is conceptually pass |
| * by value. |
| * |
| * 2. Due to gawk internals, after using sym_update() to install an array |
| * into gawk, you have to retrieve the array cookie from the value |
| * passed in to sym_update(). Like so: |
| * |
| * new_array = create_array(); |
| * val.val_type = AWK_ARRAY; |
| * val.array_cookie = new_array; |
| * sym_update("array", & val); // install array in the symbol table |
| * |
| * new_array = val.array_cookie; // MUST DO THIS |
| * |
| * // fill in new array with lots of subscripts and values |
| * |
| * Similarly, if installing a new array as a subarray of an existing |
| * array, you must add the new array to its parent before adding any |
| * elements to it. |
| * |
| * You must also retrieve the value of the array_cookie after the call |
| * to set_element(). |
| * |
| * Thus, the correct way to build an array is to work "top down". |
| * Create the array, and immediately install it in gawk's symbol table |
| * using sym_update(), or install it as an element in a previously |
| * existing array using set_element(). |
| * |
| * Thus the new array must ultimately be rooted in a global symbol. This is |
| * necessary before installing any subarrays in it, due to gawk's |
| * internal implementation. Strictly speaking, this is required only |
| * for arrays that will have subarrays as elements; however it is |
| * a good idea to always do this. This restriction may be relaxed |
| * in a subsequent revision of the API. |
| */ |
| |
| /* Allow use in C++ code. */ |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /* This is used to keep extensions from modifying certain fields in some structs. */ |
| #ifdef GAWK |
| #define awk_const |
| #else |
| #define awk_const const |
| #endif |
| |
| typedef enum awk_bool { |
| awk_false = 0, |
| awk_true |
| } awk_bool_t; /* we don't use <stdbool.h> on purpose */ |
| |
| /* The information about input files that input parsers need to know: */ |
| typedef struct awk_input { |
| const char *name; /* filename */ |
| int fd; /* file descriptor */ |
| #define INVALID_HANDLE (-1) |
| void *opaque; /* private data for input parsers */ |
| /* |
| * The get_record function is called to read the next record of data. |
| * |
| * It should return the length of the input record or EOF, and it |
| * should set *out to point to the contents of $0. The rt_start |
| * and rt_len arguments should be used to return RT to gawk. |
| * If EOF is not returned, the parser must set *rt_len (and |
| * *rt_start if *rt_len is non-zero). |
| * |
| * Note that gawk will make a copy of the record in *out, so the |
| * parser is responsible for managing its own memory buffer. |
| * Similarly, gawk will make its own copy of RT, so the parser |
| * is also responsible for managing this memory. |
| * |
| * It is guaranteed that errcode is a valid pointer, so there is |
| * no need to test for a NULL value. Gawk sets *errcode to 0, |
| * so there is no need to set it unless an error occurs. |
| * |
| * If an error does occur, the function should return EOF and set |
| * *errcode to a non-zero value. In that case, if *errcode does not |
| * equal -1, gawk will automatically update the ERRNO variable based |
| * on the value of *errcode (e.g., setting *errcode = errno should do |
| * the right thing). |
| */ |
| int (*get_record)(char **out, struct awk_input *iobuf, int *errcode, |
| char **rt_start, size_t *rt_len); |
| |
| /* |
| * No argument prototype on read_func to allow for older systems |
| * whose headers are not up to date. |
| */ |
| ssize_t (*read_func)(); |
| |
| /* |
| * The close_func is called to allow the parser to free private data. |
| * Gawk itself will close the fd unless close_func first sets it to |
| * INVALID_HANDLE. |
| */ |
| void (*close_func)(struct awk_input *iobuf); |
| |
| /* put last, for alignment. bleah */ |
| struct stat sbuf; /* stat buf */ |
| |
| } awk_input_buf_t; |
| |
| typedef struct awk_input_parser { |
| const char *name; /* name of parser */ |
| |
| /* |
| * The can_take_file function should return non-zero if the parser |
| * would like to parse this file. It should not change any gawk |
| * state! |
| */ |
| awk_bool_t (*can_take_file)(const awk_input_buf_t *iobuf); |
| |
| /* |
| * If this parser is selected, then take_control_of will be called. |
| * It can assume that a previous call to can_take_file was successful, |
| * and no gawk state has changed since that call. It should populate |
| * the awk_input_buf_t's get_record, close_func, and opaque values as needed. |
| * It should return non-zero if successful. |
| */ |
| awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf); |
| |
| awk_const struct awk_input_parser *awk_const next; /* for use by gawk */ |
| } awk_input_parser_t; |
| |
| /* |
| * Similar for output wrapper. |
| */ |
| |
| /* First the data structure */ |
| typedef struct awk_output_buf { |
| const char *name; /* name of output file */ |
| const char *mode; /* mode argument to fopen */ |
| FILE *fp; /* stdio file pointer */ |
| awk_bool_t redirected; /* true if a wrapper is active */ |
| void *opaque; /* for use by output wrapper */ |
| |
| /* |
| * Replacement functions for I/O. Just like the regular |
| * versions but also take the opaque pointer argument. |
| */ |
| size_t (*gawk_fwrite)(const void *buf, size_t size, size_t count, |
| FILE *fp, void *opaque); |
| int (*gawk_fflush)(FILE *fp, void *opaque); |
| int (*gawk_ferror)(FILE *fp, void *opaque); |
| int (*gawk_fclose)(FILE *fp, void *opaque); |
| } awk_output_buf_t; |
| |
| /* Next the output wrapper registered with gawk */ |
| typedef struct awk_output_wrapper { |
| const char *name; /* name of the wrapper */ |
| |
| /* |
| * The can_take_file function should return non-zero if the wrapper |
| * would like to process this file. It should not change any gawk |
| * state! |
| */ |
| awk_bool_t (*can_take_file)(const awk_output_buf_t *outbuf); |
| |
| /* |
| * If this wrapper is selected, then take_control_of will be called. |
| * It can assume that a previous call to can_take_file was successful, |
| * and no gawk state has changed since that call. It should populate |
| * the awk_output_buf_t function pointers and opaque pointer as needed. |
| * It should return non-zero if successful. |
| */ |
| awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf); |
| |
| awk_const struct awk_output_wrapper *awk_const next; /* for use by gawk */ |
| } awk_output_wrapper_t; |
| |
| /* A two-way processor combines an input parser and an output wrapper. */ |
| typedef struct awk_two_way_processor { |
| const char *name; /* name of the two-way processor */ |
| |
| /* |
| * The can_take_file function should return non-zero if the two-way |
| * processor would like to parse this file. It should not change |
| * any gawk state! |
| */ |
| awk_bool_t (*can_take_two_way)(const char *name); |
| |
| /* |
| * If this processor is selected, then take_control_of will be called. |
| * It can assume that a previous call to can_take_file was successful, |
| * and no gawk state has changed since that call. It should populate |
| * the awk_input_buf_t and awk_otuput_buf_t structures as needed. |
| * It should return non-zero if successful. |
| */ |
| awk_bool_t (*take_control_of)(const char *name, awk_input_buf_t *inbuf, |
| awk_output_buf_t *outbuf); |
| |
| awk_const struct awk_two_way_processor *awk_const next; /* for use by gawk */ |
| } awk_two_way_processor_t; |
| |
| /* Current version of the API. */ |
| enum { |
| GAWK_API_MAJOR_VERSION = 1, |
| GAWK_API_MINOR_VERSION = 0 |
| }; |
| |
| /* A number of typedefs related to different types of values. */ |
| |
| /* |
| * A mutable string. Gawk owns the memory pointed to if it supplied |
| * the value. Otherwise, it takes ownership of the memory pointed to. |
| * |
| * The API deals exclusively with regular chars; these strings may |
| * be multibyte encoded in the current locale's encoding and character |
| * set. Gawk will convert internally to wide characters if necessary. |
| */ |
| typedef struct awk_string { |
| char *str; /* data */ |
| size_t len; /* length thereof, in chars */ |
| } awk_string_t; |
| |
| /* Arrays are represented as an opaque type. */ |
| typedef void *awk_array_t; |
| |
| /* Scalars can be represented as an opaque type. */ |
| typedef void *awk_scalar_t; |
| |
| /* Any value can be stored as a cookie. */ |
| typedef void *awk_value_cookie_t; |
| |
| /* |
| * This tag defines the type of a value. |
| * |
| * Values are associated with regular variables and with array elements. |
| * Since arrays can be multidimensional (as can regular variables) |
| * it's valid to have a "value" that is actually an array. |
| */ |
| typedef enum { |
| AWK_UNDEFINED, |
| AWK_NUMBER, |
| AWK_STRING, |
| AWK_ARRAY, |
| AWK_SCALAR, /* opaque access to a variable */ |
| AWK_VALUE_COOKIE /* for updating a previously created value */ |
| } awk_valtype_t; |
| |
| /* |
| * An awk value. The val_type tag indicates what |
| * is in the union. |
| */ |
| typedef struct awk_value { |
| awk_valtype_t val_type; |
| union { |
| awk_string_t s; |
| double d; |
| awk_array_t a; |
| awk_scalar_t scl; |
| awk_value_cookie_t vc; |
| } u; |
| #define str_value u.s |
| #define num_value u.d |
| #define array_cookie u.a |
| #define scalar_cookie u.scl |
| #define value_cookie u.vc |
| } awk_value_t; |
| |
| /* |
| * A "flattened" array element. Gawk produces an array of these |
| * inside the awk_flat_array_t. |
| * ALL memory pointed to belongs to gawk. Individual elements may |
| * be marked for deletion. New elements must be added individually, |
| * one at a time, using the separate API for that purpose. |
| */ |
| |
| typedef struct awk_element { |
| /* convenience linked list pointer, not used by gawk */ |
| struct awk_element *next; |
| enum { |
| AWK_ELEMENT_DEFAULT = 0, /* set by gawk */ |
| AWK_ELEMENT_DELETE = 1 /* set by extension if |
| should be deleted */ |
| } flags; |
| awk_value_t index; |
| awk_value_t value; |
| } awk_element_t; |
| |
| /* |
| * A "flattened" array. See the description above for how |
| * to use the elements contained herein. |
| */ |
| typedef struct awk_flat_array { |
| awk_const void *awk_const opaque1; /* private data for use by gawk */ |
| awk_const void *awk_const opaque2; /* private data for use by gawk */ |
| awk_const size_t count; /* how many elements */ |
| awk_element_t elements[1]; /* will be extended */ |
| } awk_flat_array_t; |
| |
| /* |
| * A record describing an extension function. Upon being |
| * loaded, the extension should pass in one of these to gawk for |
| * each C function. |
| * |
| * Each called function must fill in the result with either a number |
| * or string. Gawk takes ownership of any string memory. |
| * |
| * The called function must return the value of `result'. |
| * This is for the convenience of the calling code inside gawk. |
| * |
| * Each extension function may decide what to do if the number of |
| * arguments isn't what it expected. Following awk functions, it |
| * is likely OK to ignore extra arguments. |
| */ |
| typedef struct awk_ext_func { |
| const char *name; |
| awk_value_t *(*function)(int num_actual_args, awk_value_t *result); |
| size_t num_expected_args; |
| } awk_ext_func_t; |
| |
| typedef void *awk_ext_id_t; /* opaque type for extension id */ |
| |
| /* |
| * The API into gawk. Lots of functions here. We hope that they are |
| * logically organized. |
| */ |
| typedef struct gawk_api { |
| /* First, data fields. */ |
| |
| /* These are what gawk thinks the API version is. */ |
| awk_const int major_version; |
| awk_const int minor_version; |
| |
| /* |
| * These can change on the fly as things happen within gawk. |
| * Currently only do_lint is prone to change, but we reserve |
| * the right to allow the others to do so also. |
| */ |
| #define DO_FLAGS_SIZE 6 |
| awk_const int do_flags[DO_FLAGS_SIZE]; |
| /* Use these as indices into do_flags[] array to check the values */ |
| #define gawk_do_lint 0 |
| #define gawk_do_traditional 1 |
| #define gawk_do_profile 2 |
| #define gawk_do_sandbox 3 |
| #define gawk_do_debug 4 |
| #define gawk_do_mpfr 5 |
| |
| /* Next, registration functions: */ |
| |
| /* Add a function to the interpreter, returns true upon success */ |
| awk_bool_t (*api_add_ext_func)(awk_ext_id_t id, const char *namespace, |
| const awk_ext_func_t *func); |
| |
| /* Register an input parser; for opening files read-only */ |
| void (*api_register_input_parser)(awk_ext_id_t id, |
| awk_input_parser_t *input_parser); |
| |
| /* Register an output wrapper, for writing files */ |
| void (*api_register_output_wrapper)(awk_ext_id_t id, |
| awk_output_wrapper_t *output_wrapper); |
| |
| /* Register a processor for two way I/O */ |
| void (*api_register_two_way_processor)(awk_ext_id_t id, |
| awk_two_way_processor_t *two_way_processor); |
| |
| /* |
| * Add an exit call back. |
| * |
| * arg0 is a private data pointer for use by the extension; |
| * gawk saves it and passes it into the function pointed |
| * to by funcp at exit. |
| * |
| * Exit callback functions are called in LIFO order. |
| */ |
| void (*api_awk_atexit)(awk_ext_id_t id, |
| void (*funcp)(void *data, int exit_status), |
| void *arg0); |
| |
| /* Register a version string for this extension with gawk. */ |
| void (*api_register_ext_version)(awk_ext_id_t id, const char *version); |
| |
| /* Functions to print messages */ |
| void (*api_fatal)(awk_ext_id_t id, const char *format, ...); |
| void (*api_warning)(awk_ext_id_t id, const char *format, ...); |
| void (*api_lintwarn)(awk_ext_id_t id, const char *format, ...); |
| |
| /* Functions to update ERRNO */ |
| void (*api_update_ERRNO_int)(awk_ext_id_t id, int errno_val); |
| void (*api_update_ERRNO_string)(awk_ext_id_t id, const char *string); |
| void (*api_unset_ERRNO)(awk_ext_id_t id); |
| |
| /* |
| * All of the functions that return a value from inside gawk |
| * (get a parameter, get a global variable, get an array element) |
| * behave in the same way. |
| * |
| * For a function parameter, the return is false if the argument |
| * count is out of range, or if actual paramater does not match |
| * what is specified in wanted. In that case, result->val_type |
| * will hold the actual type of what was passed. |
| * |
| * Similarly for symbol table access to variables and array elements, |
| * the return is false if the actual variable or array element does |
| * not match what was requested, and the result->val_type will hold |
| * the actual type. |
| |
| Table entry is type returned: |
| |
| |
| +-------------------------------------------------+ |
| | Type of Actual Value: | |
| +------------+------------+-----------+-----------+ |
| | String | Number | Array | Undefined | |
| +-----------+-----------+------------+------------+-----------+-----------+ |
| | | String | String | String | false | false | |
| | |-----------+------------+------------+-----------+-----------+ |
| | | Number | Number if | Number | false | false | |
| | | | can be | | | | |
| | | | converted, | | | | |
| | | | else false | | | | |
| | |-----------+------------+------------+-----------+-----------+ |
| | Type | Array | false | false | Array | false | |
| | Requested |-----------+------------+------------+-----------+-----------+ |
| | | Scalar | Scalar | Scalar | false | false | |
| | |-----------+------------+------------+-----------+-----------+ |
| | | Undefined | String | Number | Array | Undefined | |
| | |-----------+------------+------------+-----------+-----------+ |
| | | Value | false | false | false | false | |
| | | Cookie | | | | | |
| +-----------+-----------+------------+------------+-----------+-----------+ |
| */ |
| |
| /* Functions to handle parameters passed to the extension. */ |
| |
| /* |
| * Get the count'th paramater, zero-based. |
| * Returns false if count is out of range, or if actual paramater |
| * does not match what is specified in wanted. In that case, |
| * result->val_type is as described above. |
| */ |
| awk_bool_t (*api_get_argument)(awk_ext_id_t id, size_t count, |
| awk_valtype_t wanted, |
| awk_value_t *result); |
| |
| /* |
| * Convert a paramter that was undefined into an array |
| * (provide call-by-reference for arrays). Returns false |
| * if count is too big, or if the argument's type is |
| * not undefined. |
| */ |
| awk_bool_t (*api_set_argument)(awk_ext_id_t id, |
| size_t count, |
| awk_array_t array); |
| |
| /* |
| * Symbol table access: |
| * - Read-only access to special variables (NF, etc.) |
| * - One special exception: PROCINFO. |
| * - Use sym_update() to change a value, including from UNDEFINED |
| * to scalar or array. |
| */ |
| /* |
| * Lookup a variable, fill in value. No messing with the value |
| * returned. |
| * Returns false if the variable doesn't exist* or if the wrong type |
| * was requested. In the latter case, vaule->val_type will have |
| * the real type, as described above. |
| * |
| * awk_value_t val; |
| * if (! api->sym_lookup(id, name, wanted, & val)) |
| * error_code_here(); |
| * else { |
| * // safe to use val |
| * } |
| */ |
| awk_bool_t (*api_sym_lookup)(awk_ext_id_t id, |
| const char *name, |
| awk_valtype_t wanted, |
| awk_value_t *result); |
| |
| /* |
| * Update a value. Adds it to the symbol table if not there. |
| * Changing types (scalar <--> array) is not allowed. |
| * In fact, using this to update an array is not allowed, either. |
| * Such an attempt returns false. |
| */ |
| awk_bool_t (*api_sym_update)(awk_ext_id_t id, |
| const char *name, |
| awk_value_t *value); |
| |
| /* |
| * A ``scalar cookie'' is an opaque handle that provide access |
| * to a global variable or array. It is an optimization that |
| * avoids looking up variables in gawk's symbol table every time |
| * access is needed. |
| * |
| * This function retrieves the current value of a scalar cookie. |
| * Once you have obtained a scalar_cookie using sym_lookup, you can |
| * use this function to get its value more efficiently. |
| * |
| * Return will be false if the value cannot be retrieved. |
| * |
| * Flow is thus |
| * awk_value_t val; |
| * awk_scalar_t cookie; |
| * api->sym_lookup(id, "variable", AWK_SCALAR, & val); // get the cookie |
| * cookie = val.scalar_cookie; |
| * ... |
| * api->sym_lookup_scalar(id, cookie, wanted, & val); // get the value |
| */ |
| awk_bool_t (*api_sym_lookup_scalar)(awk_ext_id_t id, |
| awk_scalar_t cookie, |
| awk_valtype_t wanted, |
| awk_value_t *result); |
| |
| /* |
| * Update the value associated with a scalar cookie. |
| * Flow is |
| * sym_lookup with wanted == AWK_SCALAR |
| * if returns false |
| * sym_update with real initial value to install it |
| * sym_lookup again with AWK_SCALAR |
| * else |
| * use the scalar cookie |
| * |
| * Return will be false if the new value is not one of |
| * AWK_STRING or AWK_NUMBER. |
| * |
| * Here too, the built-in variables may not be updated. |
| */ |
| awk_bool_t (*api_sym_update_scalar)(awk_ext_id_t id, |
| awk_scalar_t cookie, awk_value_t *value); |
| |
| /* Cached values */ |
| |
| /* |
| * Create a cached string or numeric value for efficient later |
| * assignment. This improves performance when you want to assign |
| * the same value to one or more variables repeatedly. Only |
| * AWK_NUMBER and AWK_STRING values are allowed. Any other type |
| * is rejected. We disallow AWK_UNDEFINED since that case would |
| * result in inferior performance. |
| */ |
| awk_bool_t (*api_create_value)(awk_ext_id_t id, awk_value_t *value, |
| awk_value_cookie_t *result); |
| |
| /* |
| * Release the memory associated with a cookie from api_create_value. |
| * Please call this to free memory when the value is no longer needed. |
| */ |
| awk_bool_t (*api_release_value)(awk_ext_id_t id, awk_value_cookie_t vc); |
| |
| /* Array management */ |
| |
| /* |
| * Retrieve total number of elements in array. |
| * Returns false if some kind of error. |
| */ |
| awk_bool_t (*api_get_element_count)(awk_ext_id_t id, |
| awk_array_t a_cookie, size_t *count); |
| |
| /* |
| * Return the value of an element - read only! |
| * Use set_array_element() to change it. |
| * Behavior for value and return is same as for api_get_argument |
| * and sym_lookup. |
| */ |
| awk_bool_t (*api_get_array_element)(awk_ext_id_t id, |
| awk_array_t a_cookie, |
| const awk_value_t *const index, |
| awk_valtype_t wanted, |
| awk_value_t *result); |
| |
| /* |
| * Change (or create) element in existing array with |
| * index and value. |
| * |
| * ARGV and ENVIRON may not be updated. |
| */ |
| awk_bool_t (*api_set_array_element)(awk_ext_id_t id, awk_array_t a_cookie, |
| const awk_value_t *const index, |
| const awk_value_t *const value); |
| |
| /* |
| * Remove the element with the given index. |
| * Returns success if removed or false if element did not exist. |
| */ |
| awk_bool_t (*api_del_array_element)(awk_ext_id_t id, |
| awk_array_t a_cookie, const awk_value_t* const index); |
| |
| /* Create a new array cookie to which elements may be added */ |
| awk_array_t (*api_create_array)(awk_ext_id_t id); |
| |
| /* Clear out an array */ |
| awk_bool_t (*api_clear_array)(awk_ext_id_t id, awk_array_t a_cookie); |
| |
| /* Flatten out an array so that it can be looped over easily. */ |
| awk_bool_t (*api_flatten_array)(awk_ext_id_t id, |
| awk_array_t a_cookie, |
| awk_flat_array_t **data); |
| |
| /* When done, delete any marked elements, release the memory. */ |
| awk_bool_t (*api_release_flattened_array)(awk_ext_id_t id, |
| awk_array_t a_cookie, |
| awk_flat_array_t *data); |
| } gawk_api_t; |
| |
| #ifndef GAWK /* these are not for the gawk code itself! */ |
| /* |
| * Use these if you want to define "global" variables named api |
| * and ext_id to make the code a little easier to read. |
| * See the sample boilerplate code, below. |
| */ |
| #define do_lint (api->do_flags[gawk_do_lint]) |
| #define do_traditional (api->do_flags[gawk_do_traditional]) |
| #define do_profile (api->do_flags[gawk_do_profile]) |
| #define do_sandbox (api->do_flags[gawk_do_sandbox]) |
| #define do_debug (api->do_flags[gawk_do_debug]) |
| #define do_mpfr (api->do_flags[gawk_do_mpfr]) |
| |
| #define get_argument(count, wanted, result) \ |
| (api->api_get_argument(ext_id, count, wanted, result)) |
| #define set_argument(count, new_array) \ |
| (api->api_set_argument(ext_id, count, new_array)) |
| |
| #define fatal api->api_fatal |
| #define warning api->api_warning |
| #define lintwarn api->api_lintwarn |
| |
| #define register_input_parser(parser) (api->api_register_input_parser(ext_id, parser)) |
| #define register_output_wrapper(wrapper) (api->api_register_output_wrapper(ext_id, wrapper)) |
| #define register_two_way_processor(processor) \ |
| (api->api_register_two_way_processor(ext_id, processor)) |
| |
| #define update_ERRNO_int(e) (api->api_update_ERRNO_int(ext_id, e)) |
| #define update_ERRNO_string(str) \ |
| (api->api_update_ERRNO_string(ext_id, str)) |
| #define unset_ERRNO() (api->api_unset_ERRNO(ext_id)) |
| |
| #define add_ext_func(ns, func) (api->api_add_ext_func(ext_id, ns, func)) |
| #define awk_atexit(funcp, arg0) (api->api_awk_atexit(ext_id, funcp, arg0)) |
| |
| #define sym_lookup(name, wanted, result) \ |
| (api->api_sym_lookup(ext_id, name, wanted, result)) |
| #define sym_lookup_scalar(scalar_cookie, wanted, result) \ |
| (api->api_sym_lookup_scalar(ext_id, scalar_cookie, wanted, result)) |
| #define sym_update(name, value) \ |
| (api->api_sym_update(ext_id, name, value)) |
| #define sym_update_scalar(scalar_cookie, value) \ |
| (api->api_sym_update_scalar)(ext_id, scalar_cookie, value) |
| |
| #define get_array_element(array, index, wanted, result) \ |
| (api->api_get_array_element(ext_id, array, index, wanted, result)) |
| |
| #define set_array_element(array, index, value) \ |
| (api->api_set_array_element(ext_id, array, index, value)) |
| |
| #define set_array_element_by_elem(array, elem) \ |
| (api->api_set_array_element(ext_id, array, & (elem)->index, & (elem)->value)) |
| |
| #define del_array_element(array, index) \ |
| (api->api_del_array_element(ext_id, array, index)) |
| |
| #define get_element_count(array, count_p) \ |
| (api->api_get_element_count(ext_id, array, count_p)) |
| |
| #define create_array() (api->api_create_array(ext_id)) |
| |
| #define clear_array(array) (api->api_clear_array(ext_id, array)) |
| |
| #define flatten_array(array, data) \ |
| (api->api_flatten_array(ext_id, array, data)) |
| |
| #define release_flattened_array(array, data) \ |
| (api->api_release_flattened_array(ext_id, array, data)) |
| |
| #define create_value(value, result) \ |
| (api->api_create_value(ext_id, value,result)) |
| |
| #define release_value(value) \ |
| (api->api_release_value(ext_id, value)) |
| |
| #define register_ext_version(version) \ |
| (api->api_register_ext_version(ext_id, version)) |
| |
| #define emalloc(pointer, type, size, message) \ |
| do { \ |
| if ((pointer = (type) malloc(size)) == 0) \ |
| fatal(ext_id, "%s: malloc of %d bytes failed\n", message, size); \ |
| } while(0) |
| |
| #define erealloc(pointer, type, size, message) \ |
| do { \ |
| if ((pointer = (type) realloc(pointer, size)) == 0) \ |
| fatal(ext_id, "%s: realloc of %d bytes failed\n", message, size); \ |
| } while(0) |
| |
| /* Constructor functions */ |
| |
| /* r_make_string --- make a string value in result from the passed-in string */ |
| |
| static inline awk_value_t * |
| r_make_string(const gawk_api_t *api, /* needed for emalloc */ |
| awk_ext_id_t *ext_id, /* ditto */ |
| const char *string, |
| size_t length, |
| awk_bool_t duplicate, |
| awk_value_t *result) |
| { |
| char *cp = NULL; |
| |
| memset(result, 0, sizeof(*result)); |
| |
| result->val_type = AWK_STRING; |
| result->str_value.len = length; |
| |
| if (duplicate) { |
| emalloc(cp, char *, length + 2, "r_make_string"); |
| memcpy(cp, string, length); |
| cp[length] = '\0'; |
| result->str_value.str = cp; |
| } else { |
| result->str_value.str = (char *) string; |
| } |
| |
| return result; |
| } |
| |
| #define make_const_string(str, len, result) r_make_string(api, ext_id, str, len, 1, result) |
| #define make_malloced_string(str, len, result) r_make_string(api, ext_id, str, len, 0, result) |
| |
| /* make_null_string --- make a null string value */ |
| |
| static inline awk_value_t * |
| make_null_string(awk_value_t *result) |
| { |
| memset(result, 0, sizeof(*result)); |
| result->val_type = AWK_UNDEFINED; |
| |
| return result; |
| } |
| |
| /* make_number --- make a number value in result */ |
| |
| static inline awk_value_t * |
| make_number(double num, awk_value_t *result) |
| { |
| memset(result, 0, sizeof(*result)); |
| |
| result->val_type = AWK_NUMBER; |
| result->num_value = num; |
| |
| return result; |
| } |
| |
| /* |
| * Each extension must define a function with this prototype: |
| * |
| * int dl_load(gawk_api_t *api_p, awk_ext_id_t id) |
| * |
| * The return value should be zero on failure and non-zero on success. |
| * |
| * For the macros to work, the function should save api_p in a global |
| * variable named 'api' and save id in a global variable named 'ext_id'. |
| * In addition, a global function pointer named 'init_func' should be |
| * defined and set to either NULL or an initialization function that |
| * returns non-zero on success and zero upon failure. |
| */ |
| |
| extern int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id); |
| |
| #if 0 |
| /* Boiler plate code: */ |
| int plugin_is_GPL_compatible; |
| |
| static gawk_api_t *const api; |
| static awk_ext_id_t ext_id; |
| static const char *ext_version = NULL; /* or ... = "some string" */ |
| |
| static awk_ext_func_t func_table[] = { |
| { "name", do_name, 1 }, |
| /* ... */ |
| }; |
| |
| /* EITHER: */ |
| |
| static awk_bool_t (*init_func)(void) = NULL; |
| |
| /* OR: */ |
| |
| static awk_bool_t |
| init_my_module(void) |
| { |
| ... |
| } |
| |
| static awk_bool_t (*init_func)(void) = init_my_module; |
| |
| dl_load_func(func_table, some_name, "name_space_in_quotes") |
| #endif |
| |
| #define dl_load_func(func_table, module, name_space) \ |
| int dl_load(const gawk_api_t *const api_p, awk_ext_id_t id) \ |
| { \ |
| size_t i, j; \ |
| int errors = 0; \ |
| \ |
| api = api_p; \ |
| ext_id = id; \ |
| \ |
| if (api->major_version != GAWK_API_MAJOR_VERSION \ |
| || api->minor_version < GAWK_API_MINOR_VERSION) { \ |
| fprintf(stderr, #module ": version mismatch with gawk!\n"); \ |
| fprintf(stderr, "\tmy version (%d, %d), gawk version (%d, %d)\n", \ |
| GAWK_API_MAJOR_VERSION, GAWK_API_MINOR_VERSION, \ |
| api->major_version, api->minor_version); \ |
| exit(1); \ |
| } \ |
| \ |
| /* load functions */ \ |
| for (i = 0, j = sizeof(func_table) / sizeof(func_table[0]); i < j; i++) { \ |
| if (func_table[i].name == NULL) \ |
| break; \ |
| if (! add_ext_func(name_space, & func_table[i])) { \ |
| warning(ext_id, #module ": could not add %s\n", \ |
| func_table[i].name); \ |
| errors++; \ |
| } \ |
| } \ |
| \ |
| if (init_func != NULL) { \ |
| if (! init_func()) { \ |
| warning(ext_id, #module ": initialization function failed\n"); \ |
| errors++; \ |
| } \ |
| } \ |
| \ |
| if (ext_version != NULL) \ |
| register_ext_version(ext_version); \ |
| \ |
| return (errors == 0); \ |
| } |
| |
| #endif /* GAWK */ |
| |
| #ifdef __cplusplus |
| } |
| #endif /* C++ */ |
| |
| #endif /* _GAWK_API_H */ |