diff options
Diffstat (limited to 'doc/gawk.info')
| -rw-r--r-- | doc/gawk.info | 348 |
1 files changed, 181 insertions, 167 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index 6bd26e9c..b74c023c 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -21352,9 +21352,8 @@ File: gawk.info, Node: Dynamic Extensions, Next: Language History, Prev: Arbi It is possible to add new built-in functions to `gawk' using dynamically loaded libraries. This facility is available on systems -(such as GNU/Linux) that support the C `dlopen()' and `dlsym()' -functions. This major node describes how to create extensions using -code written in C or C++. +that support the C `dlopen()' and `dlsym()' functions. This major node +describes how to create extensions using code written in C or C++. If you don't know anything about C programming, you can safely skip this major node, although you may wish to review the documentation on @@ -21397,8 +21396,8 @@ write in C or C++, you can write an extension to do it! Extensions are written in C or C++, using the "Application Programming Interface" (API) defined for this purpose by the `gawk' developers. The rest of this major node explains the design decisions -behind the API, the facilities it provides and how to use them, and -presents a small sample extension. In addition, it documents the +behind the API, the facilities that it provides and how to use them, +and presents a small sample extension. In addition, it documents the sample extensions included in the `gawk' distribution, and describes the `gawkextlib' project. @@ -21557,7 +21556,7 @@ File: gawk.info, Node: Extension Other Design Decisions, Next: Extension Mecha 16.3.3 Other Design Decisions ----------------------------- -As an "arbitrary" design decision, extensions can read the values of +As an arbitrary design decision, extensions can read the values of built-in variables and arrays (such as `ARGV' and `FS'), but cannot change them, with the exception of `PROCINFO'. @@ -21583,6 +21582,13 @@ being brought out to the API in order to keep things simple and close to traditional `awk' semantics. (In fact, arrays indexed internally by integers are so transparent that they aren't even documented!) + Additionally, all functions in the API check that their pointer +input parameters are not `NULL'. If they are, they return an error. +(It is a good idea for extension code to verify that pointers received +from `gawk' are not `NULL'. Such a thing should not happen, but the +`gawk' developers are only human, and they have been known to +occasionally make mistakes.) + With time, the API will undoubtedly evolve; the `gawk' developers expect this to be driven by user needs. For now, the current API seems to provide a minimal yet powerful set of features for creating @@ -21686,10 +21692,10 @@ printing messages, setting `ERRNO', and so on. through the function pointers look like regular function calls so that extension code is quite readable and understandable. - Although all of this sounds medium complicated, the result is that -extension code is quite clean and straightforward. This can be seen in -the sample extensions `filefuncs.c' (*note Extension Example::) and -also the `testext.c' code for testing the APIs. + Although all of this sounds somewhat complicated, the result is that +extension code is quite straightforward to write and to read. You can +see this in the sample extensions `filefuncs.c' (*note Extension +Example::) and also the `testext.c' code for testing the APIs. Some other bits and pieces: @@ -21711,16 +21717,17 @@ File: gawk.info, Node: Extension Future Growth, Prev: Extension Mechanism Outl 16.3.5 Room For Future Growth ----------------------------- -The API provides room for future growth, in two ways. +The API can later be expanded, in two ways: - An "extension id" is passed into the extension when its loaded. This -extension id is then passed back to `gawk' with each function call. -This allows `gawk' to identify the extension calling into it, should it -need to know. + * `gawk' passes an "extension id" into the extension when it first + loads the extension. The extension then passes this id back to + `gawk' with each function call. This mechanism allows `gawk' to + identify the extension calling into it, should it need to know. - A "name space" is passed into `gawk' when an extension function is -registered. This provides for a future mechanism for grouping -extension functions and possibly avoiding name conflicts. + * Similarly, the extension passes a "name space" into `gawk' when it + registers each extension function. This allows a future mechanism + for grouping extension functions and possibly avoiding name + conflicts. Of course, as of this writing, no decisions have been made with respect to any of the above. @@ -21815,6 +21822,9 @@ operations: pass reasonable integer values for `ERRNO', you will need to include `<errno.h>'. + * The `gawkapi.h' file may be included more than once without ill + effect. Doing so, however, is poor coding practice. + * Although the API only uses ISO C 90 features, there is an exception; the "constructor" functions use the `inline' keyword. If your compiler does not support this keyword, you should either @@ -21852,8 +21862,8 @@ operations: While you may call the API functions by using the function pointers directly, the interface is not so pretty. To make extension code look -more like regular code, the `gawkapi.h' header file defines a number of -macros which you should use in your code. This minor node presents the +more like regular code, the `gawkapi.h' header file defines several +macros that you should use in your code. This minor node presents the macros as if they were functions. @@ -22223,8 +22233,8 @@ By default, `gawk' reads text files as its input. It uses the value of `FIELDWIDTHS') to split it into fields (*note Reading Files::). Additionally, it sets the value of `RT' (*note Built-in Variables::). - If you want, you can provide your own, custom, input parser. An -input parser's job is to return a record to the `gawk' record processing + If you want, you can provide your own custom input parser. An input +parser's job is to return a record to the `gawk' record processing code, along with indicators for the value and length of the data to be used for `RT', if any. @@ -22689,7 +22699,7 @@ termed a "symbol table". Changing types (scalar to array or vice versa) of an existing variable is _not_ allowed, nor may this routine be used to update - an array. This routine cannot be be used to update any of the + an array. This routine cannot be used to update any of the predefined variables (such as `ARGC' or `NF'). `awk_bool_t sym_constant(const char *name, awk_value_t *value);' @@ -22699,7 +22709,7 @@ termed a "symbol table". extension may change the value of `name''s variable with subsequent calls to this routine, and may also convert a variable created by `sym_update()' into a constant. However, once a - variable becomes a constant it cannot later be reverted into a + variable becomes a constant, it cannot later be reverted into a mutable variable. ---------- Footnotes ---------- @@ -22734,7 +22744,7 @@ was discussed earlier, in *note General Data Types::. too, the built-in variables may not be updated. It is not obvious at first glance how to work with scalar cookies or -what their raison d'etre really is. In theory, the `sym_lookup()' and +what their raison de^tre really is. In theory, the `sym_lookup()' and `sym_update()' routines are all you really need to work with variables. For example, you might have code that looked up the value of a variable, evaluated a condition, and then possibly changed the value of @@ -22900,7 +22910,11 @@ if `awk' code assigns a new value to `VAR1', are all the others be changed too?" That's a great question. The answer is that no, it's not a problem. -`gawk' is smart enough to avoid such problems. +Internally, `gawk' uses reference-counted strings. This means that many +variables can share the same string, and `gawk' keeps track of the +usage. When a variable's value changes, `gawk' simply decrements the +reference count on the old value and updates the variable to use the +new value. Finally, as part of your clean up action (*note Exit Callback Functions::) you should release any cached values that you created, @@ -22973,15 +22987,15 @@ The data types associated with arrays are listed below. `struct awk_element *next;' This pointer is for the convenience of extension writers. It allows an extension to create a linked list of new elements - which can then be added to an array in a loop that traverses + that can then be added to an array in a loop that traverses the list. `enum { ... } flags;' A set of flag values that convey information between `gawk' and the extension. Currently there is only one: - `AWK_ELEMENT_DELETE', which the extension can set to cause - `gawk' to delete the element from the original array upon - release of the flattened array. + `AWK_ELEMENT_DELETE'. Setting it causes `gawk' to delete the + element from the original array upon release of the flattened + array. `index' `value' @@ -23098,9 +23112,9 @@ as a nice example to show how to use the APIs. @load "testext" BEGIN { n = split("blacky rusty sophie raincloud lucky", pets) - printf "pets has %d elements\n", length(pets) + printf("pets has %d elements\n", length(pets)) ret = dump_array_and_delete("pets", "3") - printf "dump_array_and_delete(pets) returned %d\n", ret + printf("dump_array_and_delete(pets) returned %d\n", ret) if ("3" in pets) printf("dump_array_and_delete() did NOT remove index \"3\"!\n") else @@ -23280,8 +23294,8 @@ code: 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()'. Example code is - coming shortly. + previously existing array using `set_element()'. We show example + code shortly. 2. Due to gawk internals, after using `sym_update()' to install an array into `gawk', you have to retrieve the array cookie from the @@ -24537,8 +24551,8 @@ Letter File Type On systems without the file type information, calling `readdir_do_ftype("stat")' causes the extension to use the `lstat()' -system call to retrieve the appropriate information. This is not the -default, since `lstat()' is a potentially expensive operation. By +system call to retrieve the appropriate information. That is not the +default, because `lstat()' is a potentially expensive operation. By calling `readdir_do_ftype("never")' one can ensure that the file type information is never displayed, even when readily available in the directory entry. @@ -24699,10 +24713,10 @@ your script. Return the time in seconds that has elapsed since 1970-01-01 UTC as a floating point value. If the time is unavailable on this platform, return -1 and set `ERRNO'. The returned time should - have sub-second precision, but the actual precision will vary - based on the platform. If the standard C `gettimeofday()' system - call is available on this platform, then it simply returns the - value. Otherwise, if on Windows, it tries to use + have sub-second precision, but the actual precision may vary based + on the platform. If the standard C `gettimeofday()' system call + is available on this platform, then it simply returns the value. + Otherwise, if on Windows, it tries to use `GetSystemTimeAsFileTime()'. `result = sleep(SECONDS)' @@ -32107,132 +32121,132 @@ Node: Exact Arithmetic855493 Node: Arbitrary Precision Integers858601 Ref: Arbitrary Precision Integers-Footnote-1861601 Node: Dynamic Extensions861748 -Node: Extension Intro863154 -Node: Plugin License864357 -Node: Extension Design865031 -Node: Old Extension Problems866102 -Ref: Old Extension Problems-Footnote-1867612 -Node: Extension New Mechanism Goals867669 -Ref: Extension New Mechanism Goals-Footnote-1870381 -Node: Extension Other Design Decisions870567 -Node: Extension Mechanism Outline872314 -Ref: load-extension873339 -Ref: load-new-function874817 -Ref: call-new-function875798 -Node: Extension Future Growth877779 -Node: Extension API Description878521 -Node: Extension API Functions Introduction879849 -Node: General Data Types883924 -Ref: General Data Types-Footnote-1889557 -Node: Requesting Values889856 -Ref: table-value-types-returned890587 -Node: Constructor Functions891541 -Node: Registration Functions894537 -Node: Extension Functions895222 -Node: Exit Callback Functions897041 -Node: Extension Version String898284 -Node: Input Parsers898934 -Node: Output Wrappers907515 -Node: Two-way processors911908 -Node: Printing Messages914030 -Ref: Printing Messages-Footnote-1915107 -Node: Updating `ERRNO'915259 -Node: Accessing Parameters915998 -Node: Symbol Table Access917228 -Node: Symbol table by name917740 -Ref: Symbol table by name-Footnote-1919912 -Node: Symbol table by cookie919992 -Ref: Symbol table by cookie-Footnote-1924121 -Node: Cached values924184 -Ref: Cached values-Footnote-1927385 -Node: Array Manipulation927476 -Ref: Array Manipulation-Footnote-1928574 -Node: Array Data Types928613 -Ref: Array Data Types-Footnote-1931335 -Node: Array Functions931427 -Node: Flattening Arrays935193 -Node: Creating Arrays942024 -Node: Extension API Variables946820 -Node: Extension Versioning947456 -Node: Extension API Informational Variables949357 -Node: Extension API Boilerplate950443 -Node: Finding Extensions954277 -Node: Extension Example954824 -Node: Internal File Description955562 -Node: Internal File Ops959250 -Ref: Internal File Ops-Footnote-1970334 -Node: Using Internal File Ops970474 -Ref: Using Internal File Ops-Footnote-1972830 -Node: Extension Samples973096 -Node: Extension Sample File Functions974539 -Node: Extension Sample Fnmatch982908 -Node: Extension Sample Fork984634 -Node: Extension Sample Ord985848 -Node: Extension Sample Readdir986624 -Node: Extension Sample Revout988962 -Node: Extension Sample Rev2way989555 -Node: Extension Sample Read write array990245 -Node: Extension Sample Readfile992128 -Node: Extension Sample API Tests992883 -Node: Extension Sample Time993408 -Node: gawkextlib994717 -Node: Language History997098 -Node: V7/SVR3.1998620 -Node: SVR41000941 -Node: POSIX1002383 -Node: BTL1003391 -Node: POSIX/GNU1004125 -Node: Common Extensions1009660 -Node: Ranges and Locales1010767 -Ref: Ranges and Locales-Footnote-11015385 -Ref: Ranges and Locales-Footnote-21015412 -Ref: Ranges and Locales-Footnote-31015672 -Node: Contributors1015893 -Node: Installation1020189 -Node: Gawk Distribution1021083 -Node: Getting1021567 -Node: Extracting1022393 -Node: Distribution contents1024085 -Node: Unix Installation1029307 -Node: Quick Installation1029924 -Node: Additional Configuration Options1031886 -Node: Configuration Philosophy1033363 -Node: Non-Unix Installation1035705 -Node: PC Installation1036163 -Node: PC Binary Installation1037462 -Node: PC Compiling1039310 -Node: PC Testing1042254 -Node: PC Using1043430 -Node: Cygwin1047615 -Node: MSYS1048615 -Node: VMS Installation1049129 -Node: VMS Compilation1049732 -Ref: VMS Compilation-Footnote-11050739 -Node: VMS Installation Details1050797 -Node: VMS Running1052432 -Node: VMS Old Gawk1054039 -Node: Bugs1054513 -Node: Other Versions1058365 -Node: Notes1063680 -Node: Compatibility Mode1064267 -Node: Additions1065050 -Node: Accessing The Source1065977 -Node: Adding Code1067403 -Node: New Ports1073445 -Node: Derived Files1077580 -Ref: Derived Files-Footnote-11082888 -Ref: Derived Files-Footnote-21082922 -Ref: Derived Files-Footnote-31083522 -Node: Future Extensions1083620 -Node: Basic Concepts1085107 -Node: Basic High Level1085788 -Ref: figure-general-flow1086059 -Ref: figure-process-flow1086658 -Ref: Basic High Level-Footnote-11089887 -Node: Basic Data Typing1090072 -Node: Glossary1093427 -Node: Copying1118738 -Node: GNU Free Documentation License1156295 -Node: Index1181432 +Node: Extension Intro863134 +Node: Plugin License864342 +Node: Extension Design865016 +Node: Old Extension Problems866087 +Ref: Old Extension Problems-Footnote-1867597 +Node: Extension New Mechanism Goals867654 +Ref: Extension New Mechanism Goals-Footnote-1870366 +Node: Extension Other Design Decisions870552 +Node: Extension Mechanism Outline872664 +Ref: load-extension873689 +Ref: load-new-function875167 +Ref: call-new-function876148 +Node: Extension Future Growth878142 +Node: Extension API Description878960 +Node: Extension API Functions Introduction880288 +Node: General Data Types884486 +Ref: General Data Types-Footnote-1890119 +Node: Requesting Values890418 +Ref: table-value-types-returned891149 +Node: Constructor Functions892103 +Node: Registration Functions895099 +Node: Extension Functions895784 +Node: Exit Callback Functions897603 +Node: Extension Version String898846 +Node: Input Parsers899496 +Node: Output Wrappers908075 +Node: Two-way processors912468 +Node: Printing Messages914590 +Ref: Printing Messages-Footnote-1915667 +Node: Updating `ERRNO'915819 +Node: Accessing Parameters916558 +Node: Symbol Table Access917788 +Node: Symbol table by name918300 +Ref: Symbol table by name-Footnote-1920470 +Node: Symbol table by cookie920550 +Ref: Symbol table by cookie-Footnote-1924679 +Node: Cached values924742 +Ref: Cached values-Footnote-1928185 +Node: Array Manipulation928276 +Ref: Array Manipulation-Footnote-1929374 +Node: Array Data Types929413 +Ref: Array Data Types-Footnote-1932116 +Node: Array Functions932208 +Node: Flattening Arrays935974 +Node: Creating Arrays942807 +Node: Extension API Variables947602 +Node: Extension Versioning948238 +Node: Extension API Informational Variables950139 +Node: Extension API Boilerplate951225 +Node: Finding Extensions955059 +Node: Extension Example955606 +Node: Internal File Description956344 +Node: Internal File Ops960032 +Ref: Internal File Ops-Footnote-1971116 +Node: Using Internal File Ops971256 +Ref: Using Internal File Ops-Footnote-1973612 +Node: Extension Samples973878 +Node: Extension Sample File Functions975321 +Node: Extension Sample Fnmatch983690 +Node: Extension Sample Fork985416 +Node: Extension Sample Ord986630 +Node: Extension Sample Readdir987406 +Node: Extension Sample Revout989746 +Node: Extension Sample Rev2way990339 +Node: Extension Sample Read write array991029 +Node: Extension Sample Readfile992912 +Node: Extension Sample API Tests993667 +Node: Extension Sample Time994192 +Node: gawkextlib995499 +Node: Language History997880 +Node: V7/SVR3.1999402 +Node: SVR41001723 +Node: POSIX1003165 +Node: BTL1004173 +Node: POSIX/GNU1004907 +Node: Common Extensions1010442 +Node: Ranges and Locales1011549 +Ref: Ranges and Locales-Footnote-11016167 +Ref: Ranges and Locales-Footnote-21016194 +Ref: Ranges and Locales-Footnote-31016454 +Node: Contributors1016675 +Node: Installation1020971 +Node: Gawk Distribution1021865 +Node: Getting1022349 +Node: Extracting1023175 +Node: Distribution contents1024867 +Node: Unix Installation1030089 +Node: Quick Installation1030706 +Node: Additional Configuration Options1032668 +Node: Configuration Philosophy1034145 +Node: Non-Unix Installation1036487 +Node: PC Installation1036945 +Node: PC Binary Installation1038244 +Node: PC Compiling1040092 +Node: PC Testing1043036 +Node: PC Using1044212 +Node: Cygwin1048397 +Node: MSYS1049397 +Node: VMS Installation1049911 +Node: VMS Compilation1050514 +Ref: VMS Compilation-Footnote-11051521 +Node: VMS Installation Details1051579 +Node: VMS Running1053214 +Node: VMS Old Gawk1054821 +Node: Bugs1055295 +Node: Other Versions1059147 +Node: Notes1064462 +Node: Compatibility Mode1065049 +Node: Additions1065832 +Node: Accessing The Source1066759 +Node: Adding Code1068185 +Node: New Ports1074227 +Node: Derived Files1078362 +Ref: Derived Files-Footnote-11083670 +Ref: Derived Files-Footnote-21083704 +Ref: Derived Files-Footnote-31084304 +Node: Future Extensions1084402 +Node: Basic Concepts1085889 +Node: Basic High Level1086570 +Ref: figure-general-flow1086841 +Ref: figure-process-flow1087440 +Ref: Basic High Level-Footnote-11090669 +Node: Basic Data Typing1090854 +Node: Glossary1094209 +Node: Copying1119520 +Node: GNU Free Documentation License1157077 +Node: Index1182214 End Tag Table |