diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.info | 254 | ||||
| -rw-r--r-- | doc/gawk.texi | 29 | ||||
| -rw-r--r-- | gawkapi.h | 44 |
5 files changed, 195 insertions, 142 deletions
@@ -18,6 +18,11 @@ * eval.c (_t): Always define. * protos.h: Use size_t directly instead of MALLOC_ARG_T. + Unrelated: + + * gawkapi.h: Add `awk_' prefix to structure tags where they + were missing. Document the full list of include files needed. + 2012-11-14 Arnold D. Robbins <arnold@skeeve.com> * io.c (do_find_source): On VMS, don't add the `/' separater. diff --git a/doc/ChangeLog b/doc/ChangeLog index 82367979..0cb342b1 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2012-11-22 Arnold D. Robbins <arnold@skeeve.com> + + * gawk.texi: In API chapter, document the full list of include + files that need to be included. + 2012-11-21 Arnold D. Robbins <arnold@skeeve.com> * gawk.texi: In API chapter, update behavior of stat function diff --git a/doc/gawk.info b/doc/gawk.info index 9a66843c..c7f60987 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -21814,13 +21814,29 @@ operations: Some points about using the API: - * You must include `<sys/types.h>' and `<sys/stat.h>' before - including the `gawkapi.h' header file. In addition, you must - include either `<stddef.h>' or `<stdlib.h>' to get the definition - of `size_t'. If you wish to use the boilerplate `dl_load_func()' - macro, you will need to include `<stdio.h>' as well. Finally, to - pass reasonable integer values for `ERRNO', you will need to - include `<errno.h>'. + * The following types and/or macros and/or functions are referenced + in `gawkapi.h'. For correct use, you must therefore include the + corresponding standard header file _before_ including `gawkapi.h': + + C Entity Header File + ----------------------------- + `FILE' `<stdio.h>' + `NULL' `<stddef.h>' + `malloc()' `<stdlib.h>' + `memset()',`<string.h>' + `memcpy()' + `size_t' `<sys/types.h>' + `struct `<sys/stat.h>' + stat' + + 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 `gawkapi.h' 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>'. * The `gawkapi.h' file may be included more than once without ill effect. Doing so, however, is poor coding practice. @@ -32134,117 +32150,117 @@ 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-1971479 -Node: Using Internal File Ops971619 -Ref: Using Internal File Ops-Footnote-1973975 -Node: Extension Samples974241 -Node: Extension Sample File Functions975684 -Node: Extension Sample Fnmatch984157 -Node: Extension Sample Fork985883 -Node: Extension Sample Ord987097 -Node: Extension Sample Readdir987873 -Node: Extension Sample Revout989377 -Node: Extension Sample Rev2way989970 -Node: Extension Sample Read write array990660 -Node: Extension Sample Readfile992543 -Node: Extension Sample API Tests993298 -Node: Extension Sample Time993823 -Node: gawkextlib995130 -Node: Language History997511 -Node: V7/SVR3.1999033 -Node: SVR41001354 -Node: POSIX1002796 -Node: BTL1003804 -Node: POSIX/GNU1004538 -Node: Common Extensions1010073 -Node: Ranges and Locales1011180 -Ref: Ranges and Locales-Footnote-11015798 -Ref: Ranges and Locales-Footnote-21015825 -Ref: Ranges and Locales-Footnote-31016085 -Node: Contributors1016306 -Node: Installation1020602 -Node: Gawk Distribution1021496 -Node: Getting1021980 -Node: Extracting1022806 -Node: Distribution contents1024498 -Node: Unix Installation1029720 -Node: Quick Installation1030337 -Node: Additional Configuration Options1032299 -Node: Configuration Philosophy1033776 -Node: Non-Unix Installation1036118 -Node: PC Installation1036576 -Node: PC Binary Installation1037875 -Node: PC Compiling1039723 -Node: PC Testing1042667 -Node: PC Using1043843 -Node: Cygwin1048028 -Node: MSYS1049028 -Node: VMS Installation1049542 -Node: VMS Compilation1050145 -Ref: VMS Compilation-Footnote-11051152 -Node: VMS Installation Details1051210 -Node: VMS Running1052845 -Node: VMS Old Gawk1054452 -Node: Bugs1054926 -Node: Other Versions1058778 -Node: Notes1064093 -Node: Compatibility Mode1064680 -Node: Additions1065463 -Node: Accessing The Source1066390 -Node: Adding Code1067816 -Node: New Ports1073858 -Node: Derived Files1077993 -Ref: Derived Files-Footnote-11083301 -Ref: Derived Files-Footnote-21083335 -Ref: Derived Files-Footnote-31083935 -Node: Future Extensions1084033 -Node: Basic Concepts1085520 -Node: Basic High Level1086201 -Ref: figure-general-flow1086472 -Ref: figure-process-flow1087071 -Ref: Basic High Level-Footnote-11090300 -Node: Basic Data Typing1090485 -Node: Glossary1093840 -Node: Copying1119151 -Node: GNU Free Documentation License1156708 -Node: Index1181845 +Node: General Data Types884988 +Ref: General Data Types-Footnote-1890621 +Node: Requesting Values890920 +Ref: table-value-types-returned891651 +Node: Constructor Functions892605 +Node: Registration Functions895601 +Node: Extension Functions896286 +Node: Exit Callback Functions898105 +Node: Extension Version String899348 +Node: Input Parsers899998 +Node: Output Wrappers908577 +Node: Two-way processors912970 +Node: Printing Messages915092 +Ref: Printing Messages-Footnote-1916169 +Node: Updating `ERRNO'916321 +Node: Accessing Parameters917060 +Node: Symbol Table Access918290 +Node: Symbol table by name918802 +Ref: Symbol table by name-Footnote-1920972 +Node: Symbol table by cookie921052 +Ref: Symbol table by cookie-Footnote-1925181 +Node: Cached values925244 +Ref: Cached values-Footnote-1928687 +Node: Array Manipulation928778 +Ref: Array Manipulation-Footnote-1929876 +Node: Array Data Types929915 +Ref: Array Data Types-Footnote-1932618 +Node: Array Functions932710 +Node: Flattening Arrays936476 +Node: Creating Arrays943309 +Node: Extension API Variables948104 +Node: Extension Versioning948740 +Node: Extension API Informational Variables950641 +Node: Extension API Boilerplate951727 +Node: Finding Extensions955561 +Node: Extension Example956108 +Node: Internal File Description956846 +Node: Internal File Ops960534 +Ref: Internal File Ops-Footnote-1971981 +Node: Using Internal File Ops972121 +Ref: Using Internal File Ops-Footnote-1974477 +Node: Extension Samples974743 +Node: Extension Sample File Functions976186 +Node: Extension Sample Fnmatch984659 +Node: Extension Sample Fork986385 +Node: Extension Sample Ord987599 +Node: Extension Sample Readdir988375 +Node: Extension Sample Revout989879 +Node: Extension Sample Rev2way990472 +Node: Extension Sample Read write array991162 +Node: Extension Sample Readfile993045 +Node: Extension Sample API Tests993800 +Node: Extension Sample Time994325 +Node: gawkextlib995632 +Node: Language History998013 +Node: V7/SVR3.1999535 +Node: SVR41001856 +Node: POSIX1003298 +Node: BTL1004306 +Node: POSIX/GNU1005040 +Node: Common Extensions1010575 +Node: Ranges and Locales1011682 +Ref: Ranges and Locales-Footnote-11016300 +Ref: Ranges and Locales-Footnote-21016327 +Ref: Ranges and Locales-Footnote-31016587 +Node: Contributors1016808 +Node: Installation1021104 +Node: Gawk Distribution1021998 +Node: Getting1022482 +Node: Extracting1023308 +Node: Distribution contents1025000 +Node: Unix Installation1030222 +Node: Quick Installation1030839 +Node: Additional Configuration Options1032801 +Node: Configuration Philosophy1034278 +Node: Non-Unix Installation1036620 +Node: PC Installation1037078 +Node: PC Binary Installation1038377 +Node: PC Compiling1040225 +Node: PC Testing1043169 +Node: PC Using1044345 +Node: Cygwin1048530 +Node: MSYS1049530 +Node: VMS Installation1050044 +Node: VMS Compilation1050647 +Ref: VMS Compilation-Footnote-11051654 +Node: VMS Installation Details1051712 +Node: VMS Running1053347 +Node: VMS Old Gawk1054954 +Node: Bugs1055428 +Node: Other Versions1059280 +Node: Notes1064595 +Node: Compatibility Mode1065182 +Node: Additions1065965 +Node: Accessing The Source1066892 +Node: Adding Code1068318 +Node: New Ports1074360 +Node: Derived Files1078495 +Ref: Derived Files-Footnote-11083803 +Ref: Derived Files-Footnote-21083837 +Ref: Derived Files-Footnote-31084437 +Node: Future Extensions1084535 +Node: Basic Concepts1086022 +Node: Basic High Level1086703 +Ref: figure-general-flow1086974 +Ref: figure-process-flow1087573 +Ref: Basic High Level-Footnote-11090802 +Node: Basic Data Typing1090987 +Node: Glossary1094342 +Node: Copying1119653 +Node: GNU Free Documentation License1157210 +Node: Index1182347 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index f03cccd0..92d1de4e 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -28705,13 +28705,28 @@ Some points about using the API: @itemize @bullet @item -You must include @code{<sys/types.h>} and @code{<sys/stat.h>} before including -the @file{gawkapi.h} header file. In addition, you must include either -@code{<stddef.h>} or @code{<stdlib.h>} to get the definition of @code{size_t}. -If you wish to use the boilerplate @code{dl_load_func()} macro, you will -need to include @code{<stdio.h>} as well. -Finally, to pass reasonable integer values for @code{ERRNO}, you -will need to include @code{<errno.h>}. +The following types and/or macros and/or functions are referenced +in @file{gawkapi.h}. For correct use, you must therefore include the +corresponding standard header file @emph{before} including @file{gawkapi.h}: + +@multitable {C Entity} {@code{<sys/types.h>}} +@headitem C Entity @tab Header File +@item @code{FILE} @tab @code{<stdio.h>} +@item @code{NULL} @tab @code{<stddef.h>} +@item @code{malloc()} @tab @code{<stdlib.h>} +@item @code{memset()}, @code{memcpy()} @tab @code{<string.h>} +@item @code{size_t} @tab @code{<sys/types.h>} +@item @code{struct stat} @tab @code{<sys/stat.h>} +@end multitable + +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 @file{gawkapi.h} clean, instead of becoming +a portability hodge-podge as can be seen in the @command{gawk} source code. + +To pass reasonable integer values for @code{ERRNO}, you will also need to +include @code{<errno.h>}. @item The @file{gawkapi.h} file may be included more than once without ill effect. @@ -24,12 +24,24 @@ */ /* - * N.B. You must include <sys/types.h> and <sys/stat.h> - * before including this file! - * You must include <stddef.h> or <stdlib.h> to get size_t's definition. - * You should also include <stdio.h> if you intend to use - * the dl_load_func() convenience macro. - * To pass reasonable integer values for ERRNO, you will need to + * 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>. */ @@ -148,7 +160,7 @@ typedef struct awk_input { } awk_input_buf_t; -typedef struct input_parser { +typedef struct awk_input_parser { const char *name; /* name of parser */ /* @@ -167,7 +179,7 @@ typedef struct input_parser { */ awk_bool_t (*take_control_of)(awk_input_buf_t *iobuf); - awk_const struct input_parser *awk_const next; /* for use by gawk */ + awk_const struct awk_input_parser *awk_const next; /* for use by gawk */ } awk_input_parser_t; /* @@ -175,7 +187,7 @@ typedef struct input_parser { */ /* First the data structure */ -typedef struct { +typedef struct awk_output_buf { const char *name; /* name of output file */ const char *mode; /* mode argument to fopen */ FILE *fp; /* stdio file pointer */ @@ -194,7 +206,7 @@ typedef struct { } awk_output_buf_t; /* Next the output wrapper registered with gawk */ -typedef struct output_wrapper { +typedef struct awk_output_wrapper { const char *name; /* name of the wrapper */ /* @@ -213,11 +225,11 @@ typedef struct output_wrapper { */ awk_bool_t (*take_control_of)(awk_output_buf_t *outbuf); - awk_const struct output_wrapper *awk_const next; /* for use by gawk */ + 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 two_way_processor { +typedef struct awk_two_way_processor { const char *name; /* name of the two-way processor */ /* @@ -237,7 +249,7 @@ typedef struct two_way_processor { awk_bool_t (*take_control_of)(const char *name, awk_input_buf_t *inbuf, awk_output_buf_t *outbuf); - awk_const struct two_way_processor *awk_const next; /* for use by gawk */ + awk_const struct awk_two_way_processor *awk_const next; /* for use by gawk */ } awk_two_way_processor_t; /* Current version of the API. */ @@ -256,7 +268,7 @@ enum { * be multibyte encoded in the current locale's encoding and character * set. Gawk will convert internally to wide characters if necessary. */ -typedef struct { +typedef struct awk_string { char *str; /* data */ size_t len; /* length thereof, in chars */ } awk_string_t; @@ -290,7 +302,7 @@ typedef enum { * An awk value. The val_type tag indicates what * is in the union. */ -typedef struct { +typedef struct awk_value { awk_valtype_t val_type; union { awk_string_t s; @@ -352,7 +364,7 @@ typedef struct awk_flat_array { * arguments isn't what it expected. Following awk functions, it * is likely OK to ignore extra arguments. */ -typedef struct { +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; |