diff options
Diffstat (limited to 'doc/gawk.info')
| -rw-r--r-- | doc/gawk.info | 310 |
1 files changed, 167 insertions, 143 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index 3bb2f352..c197aa14 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -23859,8 +23859,13 @@ Extension functions are described by the following record: typedef struct awk_ext_func { const char *name; - awk_value_t *(*function)(int num_actual_args, awk_value_t *result); - size_t max_expected_args; + awk_value_t *(*const function)(int num_actual_args, + awk_value_t *result, + struct awk_ext_func *finfo); + const size_t min_required_args; + const size_t max_expected_args; + awk_bool_t suppress_lint; + void *data; /* opaque pointer to any extra state */ } awk_ext_func_t; The fields are: @@ -23874,7 +23879,7 @@ Extension functions are described by the following record: which may be followed by any number of letters, digits, and underscores. Letter case in function names is significant. -'awk_value_t *(*function)(int num_actual_args, awk_value_t *result);' +'awk_value_t *(*const function)(int num_actual_args, awk_value_t *result, struct awk_ext_func *finfo);' This is a pointer to the C function that provides the extension's functionality. The function must fill in '*result' with either a number or a string. 'gawk' takes ownership of any string memory. @@ -23884,20 +23889,39 @@ Extension functions are described by the following record: The 'num_actual_args' argument tells the C function how many actual parameters were passed from the calling 'awk' code. + The 'finfo' parameter is a pointer to the 'awk_ext_func_t' for this + function. The called function may access data within it as + desired, or not. + The function must return the value of 'result'. This is for the convenience of the calling code inside 'gawk'. -'size_t max_expected_args;' - This is the maximum number of arguments the function expects to - receive. Each extension function may decide what to do if the - number of arguments isn't what it expected. As with real 'awk' - functions, it is likely OK to ignore extra arguments. This value - does not affect actual program execution. +'const size_t min_required_args;' + This is the minimum number of arguments the function expects to + receive. If called with fewer arguments, 'gawk' prints a fatal + error message and exits. - Extension functions should compare this value to the number of - actual arguments passed and possibly issue a lint warning if there - is an undesirable mismatch. Of course, if '--lint=fatal' is used, - this would cause the program to exit. +'const size_t max_expected_args;' + This is the maximum number of arguments the function expects to + receive. If called with more arguments than this, and if lint + checking has been enabled, then 'gawk' prints a warning message. + For more information, see the next item in this list. + +'awk_bool_t suppress_lint;' + This flag tells 'gawk' not to print a lint message if lint checking + has been enabled and if more arguments were supplied in the call + than expected. An extension function can tell if 'gawk' already + printed at least one such message by checking if 'num_actual_args > + finfo->max_expected_args'. If so, and the function does not want + more lint messages to be printed, it should set + 'finfo->suppress_lint' to 'awk_true'. + +'void *data;' + This is an opaque pointer to any data that an extension function + may wish to have available when called. Passing the + 'awk_ext_funct_t' structure to the extension function, and having + this pointer available in it enables writing a single C or C++ + function that implements multiple 'awk'-level extension functions. Once you have a record representing your extension function, you register it with 'gawk' using this API function: @@ -35758,135 +35782,135 @@ Ref: Memory Allocation Functions-Footnote-1966474 Node: Constructor Functions966573 Node: Registration Functions968318 Node: Extension Functions969003 -Node: Exit Callback Functions971626 -Node: Extension Version String972876 -Node: Input Parsers973539 -Node: Output Wrappers983421 -Node: Two-way processors987933 -Node: Printing Messages990198 -Ref: Printing Messages-Footnote-1991369 -Node: Updating ERRNO991522 -Node: Requesting Values992261 -Ref: table-value-types-returned992998 -Node: Accessing Parameters993881 -Node: Symbol Table Access995116 -Node: Symbol table by name995628 -Node: Symbol table by cookie997649 -Ref: Symbol table by cookie-Footnote-11001801 -Node: Cached values1001865 -Ref: Cached values-Footnote-11005372 -Node: Array Manipulation1005463 -Ref: Array Manipulation-Footnote-11006554 -Node: Array Data Types1006591 -Ref: Array Data Types-Footnote-11009249 -Node: Array Functions1009341 -Node: Flattening Arrays1013199 -Node: Creating Arrays1020107 -Node: Redirection API1024876 -Node: Extension API Variables1027707 -Node: Extension Versioning1028340 -Ref: gawk-api-version1028777 -Node: Extension API Informational Variables1030533 -Node: Extension API Boilerplate1031597 -Node: Finding Extensions1035411 -Node: Extension Example1035970 -Node: Internal File Description1036768 -Node: Internal File Ops1040848 -Ref: Internal File Ops-Footnote-11052610 -Node: Using Internal File Ops1052750 -Ref: Using Internal File Ops-Footnote-11055133 -Node: Extension Samples1055407 -Node: Extension Sample File Functions1056936 -Node: Extension Sample Fnmatch1064585 -Node: Extension Sample Fork1066072 -Node: Extension Sample Inplace1067290 -Node: Extension Sample Ord1070500 -Node: Extension Sample Readdir1071336 -Ref: table-readdir-file-types1072225 -Node: Extension Sample Revout1073030 -Node: Extension Sample Rev2way1073619 -Node: Extension Sample Read write array1074359 -Node: Extension Sample Readfile1076301 -Node: Extension Sample Time1077396 -Node: Extension Sample API Tests1078744 -Node: gawkextlib1079236 -Node: Extension summary1081683 -Node: Extension Exercises1085385 -Node: Language History1086883 -Node: V7/SVR3.11088539 -Node: SVR41090691 -Node: POSIX1092125 -Node: BTL1093504 -Node: POSIX/GNU1094233 -Node: Feature History1100095 -Node: Common Extensions1114465 -Node: Ranges and Locales1115748 -Ref: Ranges and Locales-Footnote-11120364 -Ref: Ranges and Locales-Footnote-21120391 -Ref: Ranges and Locales-Footnote-31120626 -Node: Contributors1120847 -Node: History summary1126407 -Node: Installation1127787 -Node: Gawk Distribution1128731 -Node: Getting1129215 -Node: Extracting1130176 -Node: Distribution contents1131814 -Node: Unix Installation1137899 -Node: Quick Installation1138581 -Node: Shell Startup Files1140995 -Node: Additional Configuration Options1142073 -Node: Configuration Philosophy1143878 -Node: Non-Unix Installation1146247 -Node: PC Installation1146707 -Node: PC Binary Installation1147545 -Node: PC Compiling1147980 -Node: PC Using1149097 -Node: Cygwin1152142 -Node: MSYS1152912 -Node: VMS Installation1153413 -Node: VMS Compilation1154204 -Ref: VMS Compilation-Footnote-11155433 -Node: VMS Dynamic Extensions1155491 -Node: VMS Installation Details1157176 -Node: VMS Running1159429 -Node: VMS GNV1163708 -Node: VMS Old Gawk1164443 -Node: Bugs1164914 -Node: Bug address1165577 -Node: Usenet1167974 -Node: Maintainers1168749 -Node: Other Versions1170125 -Node: Installation summary1176709 -Node: Notes1177744 -Node: Compatibility Mode1178609 -Node: Additions1179391 -Node: Accessing The Source1180316 -Node: Adding Code1181751 -Node: New Ports1187970 -Node: Derived Files1192458 -Ref: Derived Files-Footnote-11197943 -Ref: Derived Files-Footnote-21197978 -Ref: Derived Files-Footnote-31198576 -Node: Future Extensions1198690 -Node: Implementation Limitations1199348 -Node: Extension Design1200531 -Node: Old Extension Problems1201685 -Ref: Old Extension Problems-Footnote-11203203 -Node: Extension New Mechanism Goals1203260 -Ref: Extension New Mechanism Goals-Footnote-11206624 -Node: Extension Other Design Decisions1206813 -Node: Extension Future Growth1208926 -Node: Old Extension Mechanism1209762 -Node: Notes summary1211525 -Node: Basic Concepts1212707 -Node: Basic High Level1213388 -Ref: figure-general-flow1213670 -Ref: figure-process-flow1214355 -Ref: Basic High Level-Footnote-11217656 -Node: Basic Data Typing1217841 -Node: Glossary1221169 -Node: Copying1253116 -Node: GNU Free Documentation License1290655 -Node: Index1315773 +Node: Exit Callback Functions972816 +Node: Extension Version String974066 +Node: Input Parsers974729 +Node: Output Wrappers984611 +Node: Two-way processors989123 +Node: Printing Messages991388 +Ref: Printing Messages-Footnote-1992559 +Node: Updating ERRNO992712 +Node: Requesting Values993451 +Ref: table-value-types-returned994188 +Node: Accessing Parameters995071 +Node: Symbol Table Access996306 +Node: Symbol table by name996818 +Node: Symbol table by cookie998839 +Ref: Symbol table by cookie-Footnote-11002991 +Node: Cached values1003055 +Ref: Cached values-Footnote-11006562 +Node: Array Manipulation1006653 +Ref: Array Manipulation-Footnote-11007744 +Node: Array Data Types1007781 +Ref: Array Data Types-Footnote-11010439 +Node: Array Functions1010531 +Node: Flattening Arrays1014389 +Node: Creating Arrays1021297 +Node: Redirection API1026066 +Node: Extension API Variables1028897 +Node: Extension Versioning1029530 +Ref: gawk-api-version1029967 +Node: Extension API Informational Variables1031723 +Node: Extension API Boilerplate1032787 +Node: Finding Extensions1036601 +Node: Extension Example1037160 +Node: Internal File Description1037958 +Node: Internal File Ops1042038 +Ref: Internal File Ops-Footnote-11053800 +Node: Using Internal File Ops1053940 +Ref: Using Internal File Ops-Footnote-11056323 +Node: Extension Samples1056597 +Node: Extension Sample File Functions1058126 +Node: Extension Sample Fnmatch1065775 +Node: Extension Sample Fork1067262 +Node: Extension Sample Inplace1068480 +Node: Extension Sample Ord1071690 +Node: Extension Sample Readdir1072526 +Ref: table-readdir-file-types1073415 +Node: Extension Sample Revout1074220 +Node: Extension Sample Rev2way1074809 +Node: Extension Sample Read write array1075549 +Node: Extension Sample Readfile1077491 +Node: Extension Sample Time1078586 +Node: Extension Sample API Tests1079934 +Node: gawkextlib1080426 +Node: Extension summary1082873 +Node: Extension Exercises1086575 +Node: Language History1088073 +Node: V7/SVR3.11089729 +Node: SVR41091881 +Node: POSIX1093315 +Node: BTL1094694 +Node: POSIX/GNU1095423 +Node: Feature History1101285 +Node: Common Extensions1115655 +Node: Ranges and Locales1116938 +Ref: Ranges and Locales-Footnote-11121554 +Ref: Ranges and Locales-Footnote-21121581 +Ref: Ranges and Locales-Footnote-31121816 +Node: Contributors1122037 +Node: History summary1127597 +Node: Installation1128977 +Node: Gawk Distribution1129921 +Node: Getting1130405 +Node: Extracting1131366 +Node: Distribution contents1133004 +Node: Unix Installation1139089 +Node: Quick Installation1139771 +Node: Shell Startup Files1142185 +Node: Additional Configuration Options1143263 +Node: Configuration Philosophy1145068 +Node: Non-Unix Installation1147437 +Node: PC Installation1147897 +Node: PC Binary Installation1148735 +Node: PC Compiling1149170 +Node: PC Using1150287 +Node: Cygwin1153332 +Node: MSYS1154102 +Node: VMS Installation1154603 +Node: VMS Compilation1155394 +Ref: VMS Compilation-Footnote-11156623 +Node: VMS Dynamic Extensions1156681 +Node: VMS Installation Details1158366 +Node: VMS Running1160619 +Node: VMS GNV1164898 +Node: VMS Old Gawk1165633 +Node: Bugs1166104 +Node: Bug address1166767 +Node: Usenet1169164 +Node: Maintainers1169939 +Node: Other Versions1171315 +Node: Installation summary1177899 +Node: Notes1178934 +Node: Compatibility Mode1179799 +Node: Additions1180581 +Node: Accessing The Source1181506 +Node: Adding Code1182941 +Node: New Ports1189160 +Node: Derived Files1193648 +Ref: Derived Files-Footnote-11199133 +Ref: Derived Files-Footnote-21199168 +Ref: Derived Files-Footnote-31199766 +Node: Future Extensions1199880 +Node: Implementation Limitations1200538 +Node: Extension Design1201721 +Node: Old Extension Problems1202875 +Ref: Old Extension Problems-Footnote-11204393 +Node: Extension New Mechanism Goals1204450 +Ref: Extension New Mechanism Goals-Footnote-11207814 +Node: Extension Other Design Decisions1208003 +Node: Extension Future Growth1210116 +Node: Old Extension Mechanism1210952 +Node: Notes summary1212715 +Node: Basic Concepts1213897 +Node: Basic High Level1214578 +Ref: figure-general-flow1214860 +Ref: figure-process-flow1215545 +Ref: Basic High Level-Footnote-11218846 +Node: Basic Data Typing1219031 +Node: Glossary1222359 +Node: Copying1254306 +Node: GNU Free Documentation License1291845 +Node: Index1316963 End Tag Table |