diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 11 | ||||
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/Makefile.in | 2 | ||||
| -rw-r--r-- | doc/gawk.info | 1334 | ||||
| -rw-r--r-- | doc/gawk.texi | 435 |
5 files changed, 852 insertions, 932 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index dffa2976..cbc0d560 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,14 @@ +Tue Dec 28 21:46:21 2010 Arnold D. Robbins <arnold@skeeve.com> + + * README.DGAWK: Removed, since there is now a chapter on the + debugger. + * Makefile.am (EXTRA_DIST): Remove README.DGAWK. + +Tue Dec 28 07:13:20 2010 John Haque <j.eh@mchsi.com> + + * gawk.texi: Update dgawk examples. Document condition command + without an expression. Fix a typo. + Tue Dec 21 10:06:05 2010 Arnold D. Robbins <arnold@skeeve.com> * Makefile.am (pdf): Renamed from `all-pdf'. Much more logical diff --git a/doc/Makefile.am b/doc/Makefile.am index c03c26bb..cd618e39 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -34,7 +34,7 @@ EXTRA_DIST = ChangeLog README.card ad.block setter.outline \ lflashlight.eps rflashlight.eps \ lflashlight.pdf rflashlight.pdf \ statist.jpg statist.eps statist.pdf \ - bc_notes README.DGAWK + bc_notes # Get rid of generated files when cleaning CLEANFILES = *.ps *.html *.dvi *~ awkcard.nc awkcard.tr gawk.pdf gawkinet.pdf awkcard.pdf gawk.1.pdf diff --git a/doc/Makefile.in b/doc/Makefile.in index 2df2e585..b094ee79 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -248,7 +248,7 @@ EXTRA_DIST = ChangeLog README.card ad.block setter.outline \ lflashlight.eps rflashlight.eps \ lflashlight.pdf rflashlight.pdf \ statist.jpg statist.eps statist.pdf \ - bc_notes README.DGAWK + bc_notes # Get rid of generated files when cleaning diff --git a/doc/gawk.info b/doc/gawk.info index d6f23a7d..13fdbc0a 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -473,6 +473,7 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Compatibility Mode:: How to disable certain `gawk' extensions. * Additions:: Making Additions To `gawk'. +* Accessing The Source:: Accessing the Git repository. * Adding Code:: Adding code to the main body of `gawk'. * New Ports:: Porting `gawk' to a new operating @@ -18437,15 +18438,13 @@ Oops! mentioned): dgawk> p @alast - -| alast["4"] = string ("wonderful") - -| alast["5"] = string ("program!") -| alast["1"] = string ("awk") -| alast["2"] = string ("is") -| alast["3"] = string ("a") + -| alast["4"] = string ("wonderful") + -| alast["5"] = string ("program!") - Ignoring the ordering of the elements for now (a `dgawk' internals -issue), it looks like we got this far OK. Let's take another step or -two: + It looks like we got this far OK. Let's take another step or two: dgawk> n -| 70 clast = join(alast, fcount, n) @@ -18571,7 +18570,9 @@ controlling breakpoints are: condition is an `awk' expression that `dgawk' evaluates whenever the breakpoint or watchpoint is reached. If the condition is true, then `dgawk' stops execution and prompts for a command. Otherwise, - `dgawk' continues executing the program. + `dgawk' continues executing the program. If the condition + expression is not specified, any existing condition is removed; + i.e., the breakpoint or watchpoint is made unconditional. `delete' [N1 N2 ...] [N-M] `d' [N1 N2 ...] [N-M] @@ -18589,7 +18590,7 @@ controlling breakpoints are: specify how to enable the breakpoint: `del' - Enable the breakpoint(s) tempoarily, then delete it when the + Enable the breakpoint(s) temporarily, then delete it when the program stops at the breakpoint. `once' @@ -18948,55 +18949,52 @@ categories, as follows: dgawk> dump -| # BEGIN -| - -| [ 2:0x1d4355f0] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] - -| [ 3:0x1d435710] Op_push_i : "~" [MALLOC|PERM|STRING|STRCUR] - -| [ 3:0x1d4357c0] Op_push_i : "~" [MALLOC|PERM|STRING|STRCUR] - -| [ 3:0x1d435790] Op_match : - -| [ 3:0x1d435680] Op_push_lhs : O [do_reference = FALSE] - -| [ 3:0x1d4356b0] Op_assign : - -| [ :0x1d4356e0] Op_pop : - -| [ 4:0x1d4358c0] Op_push_i : "==" [MALLOC|PERM|STRING|STRCUR] - -| [ 4:0x1d435970] Op_push_i : "==" [MALLOC|PERM|STRING|STRCUR] - -| [ 4:0x1d435940] Op_equal : - -| [ 4:0x1d435810] Op_push_lhs : o [do_reference = FALSE] - -| [ 4:0x1d435860] Op_assign : - -| [ :0x1d435890] Op_pop : - -| [ 5:0x1d435a70] Op_push : o - -| [ 5:0x1d435a40] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] - -| [ 5:0x1d4359c0] Op_push_lhs : o [do_reference = TRUE] - -| [ 5:0x1d435910] Op_assign_plus : - -| [ :0x1d435a10] Op_pop : - -| [ 6:0x1d435b50] Op_push : O - -| [ 6:0x1d435b80] Op_push_i : "" [MALLOC|PERM|STRING|STRCUR] - -| [ :0x1d435c60] Op_no_op : - -| [ 6:0x1d435c30] Op_push : O - -| [ :0x1d435c90] Op_concat : [expr_count = 3] - -| [ 6:0x1d435ad0] Op_push_lhs : x [do_reference = FALSE] - -| [ 6:0x1d435aa0] Op_assign : - -| [ :0x1d435b00] Op_pop : - -| [ 7:0x1d435c00] Op_push_loop : [target_continue = 0x1d435bd0] [target_break = 0x1d435fc0] - -| [ 7:0x1d435bd0] Op_push_lhs : X [do_reference = TRUE] - -| [ 7:0x1d435cc0] Op_postincrement : - -| [ 7:0x1d435d70] Op_push : x - -| [ 7:0x1d435e00] Op_push : o - -| [ 7:0x1d435da0] Op_plus : - -| [ 7:0x1d435e60] Op_push : o - -| [ 7:0x1d435e30] Op_plus : - -| [ 7:0x1d435d20] Op_leq : - -| [ :0x1d435cf0] Op_jmp_false : [target_jmp = 0x1d435fc0] - -| [ 8:0x1d435f40] Op_push_i : "%c" [MALLOC|PERM|STRING|STRCUR] - -| [ :0x1d435ff0] Op_no_op : - -| [ 8:0x1d435dd0] Op_push_lhs : c [do_reference = FALSE] - -| [ 8:0x1d435e90] Op_assign_concat : - -| [ :0x1d435ec0] Op_pop : - -| [ :0x1d435f90] Op_jmp : [target_jmp = 0x1d435bd0] - -| [ :0x1d435fc0] Op_pop_loop : + -| [ 2:0x89faef4] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] + -| [ 3:0x89fa428] Op_push_i : "~" [PERM|STRING|STRCUR] + -| [ 3:0x89fa464] Op_push_i : "~" [PERM|STRING|STRCUR] + -| [ 3:0x89fa450] Op_match : + -| [ 3:0x89fa3ec] Op_store_var : O [do_reference = FALSE] + -| [ 4:0x89fa48c] Op_push_i : "==" [PERM|STRING|STRCUR] + -| [ 4:0x89fa4c8] Op_push_i : "==" [PERM|STRING|STRCUR] + -| [ 4:0x89fa4b4] Op_equal : + -| [ 4:0x89fa400] Op_store_var : o [do_reference = FALSE] + -| [ 5:0x89fa4f0] Op_push : o + -| [ 5:0x89fa4dc] Op_plus_i : 0 [PERM|NUMCUR|NUMBER] + -| [ 5:0x89fa414] Op_push_lhs : o [do_reference = TRUE] + -| [ 5:0x89fa4a0] Op_assign_plus : + -| [ :0x89fa478] Op_pop : + -| [ 6:0x89fa540] Op_push : O + -| [ 6:0x89fa554] Op_push_i : "" [PERM|STRING|STRCUR] + -| [ :0x89fa5a4] Op_no_op : + -| [ 6:0x89fa590] Op_push : O + -| [ :0x89fa5b8] Op_concat : [expr_count = 3] [concat_flag = 0] + -| [ 6:0x89fa518] Op_store_var : x [do_reference = FALSE] + -| [ 7:0x89fa504] Op_push_loop : [target_continue = 0x89fa568] [target_break = 0x89fa680] + -| [ 7:0x89fa568] Op_push_lhs : X [do_reference = TRUE] + -| [ 7:0x89fa52c] Op_postincrement : + -| [ 7:0x89fa5e0] Op_push : x + -| [ 7:0x89fa61c] Op_push : o + -| [ 7:0x89fa5f4] Op_plus : + -| [ 7:0x89fa644] Op_push : o + -| [ 7:0x89fa630] Op_plus : + -| [ 7:0x89fa5cc] Op_leq : + -| [ :0x89fa57c] Op_jmp_false : [target_jmp = 0x89fa680] + -| [ 7:0x89fa694] Op_push_i : "%c" [PERM|STRING|STRCUR] + -| [ :0x89fa6d0] Op_no_op : + -| [ 7:0x89fa608] Op_assign_concat : c + -| [ :0x89fa6a8] Op_jmp : [target_jmp = 0x89fa568] + -| [ :0x89fa680] Op_pop_loop : -| -| ... -| - -| [ 9:0x1d435f10] Op_K_printf : [expr_count = 17] [redir_type = Op_illegal] - -| [ :0x1d435180] Op_no_op : - -| [ :0x1d435240] Op_exit : [exit_value = 0] + -| [ 8:0x89fa658] Op_K_printf : [expr_count = 17] [redir_type = ""] + -| [ :0x89fa374] Op_no_op : + -| [ :0x89fa3d8] Op_atexit : + -| [ :0x89fa6bc] Op_stop : + -| [ :0x89fa39c] Op_no_op : + -| [ :0x89fa3b0] Op_after_beginfile : + -| [ :0x89fa388] Op_no_op : + -| [ :0x89fa3c4] Op_after_endfile : dgawk> `help' @@ -20577,12 +20575,11 @@ considered authoritative if it conflicts with this Info file. The people maintaining the non-Unix ports of `gawk' are as follows: -MS-Windows using MINGW Eli Zaretskii, <eliz@gnu.org>. - Scott Deifik, <scottd.mail@sbcglobal.net>. -OS/2 Andreas Buening, <andreas.buening@nexgo.de> -Tandem (POSIX-compliant) Matthew Woehlke, <mw_triad@users.sourceforge.net> -VMS Pat Rankin, <rankin@pactechdata.com>. -z/OS (OS/390) Dave Pitts, <pitts@cozx.com>. +MS-Windows using MINGW Eli Zaretskii, <eliz@gnu.org>. + Scott Deifik, <scottd.mail@sbcglobal.net>. +OS/2 Andreas Buening, <andreas.buening@nexgo.de>. +VMS Pat Rankin, <rankin@pactechdata.com>. +z/OS (OS/390) Dave Pitts, <dpitts@cozx.com>. If your bug is also reproducible under Unix, please send a copy of your report to the <bug-gawk@gnu.org> email list as well. @@ -20781,21 +20778,57 @@ as well as any considerations you should bear in mind. * Menu: +* Accessing The Source:: Accessing the Git repository. * Adding Code:: Adding code to the main body of `gawk'. * New Ports:: Porting `gawk' to a new operating system. -File: gawk.info, Node: Adding Code, Next: New Ports, Up: Additions +File: gawk.info, Node: Accessing The Source, Next: Adding Code, Up: Additions + +C.2.1 Accessing The `gawk' Git Repository +----------------------------------------- + +As `gawk' is Free Software, the source code is always available *note +Gawk Distribution::, describes how to get and build the formal, +released versions of `gawk'. + + However, if you want to modify `gawk' and contribute back your +changes, you will probably wish to work with the development version. +To do so, you will need to access the `gawk' source code repository. +The code is maintained using the Git distributed version control system +(http://git-scm.com/). You will need to install it if your system +doesn't have it. Once you have done so, use the command: + + git clone git://git.savannah.gnu.org/gawk.git + +This will clone the `gawk' repository. If you are behind a firewall +that will not allow you to use the Git native protocol, you can still +access the repository using: + + git clone http://git.savannah.gnu.org/r/gawk.git + + Once you have made changes, you can use `git diff' to produce a +patch, and send that to the `gawk' maintainer; see *note Bugs:: for how +to do that. + + Finally, if you cannot install Git (e.g., if it hasn't been ported +yet to your operating system), you can use the Git-CVS gateway to check +out a copy using CVS, as follows: + + cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/gawk.git co -d gawk master + + +File: gawk.info, Node: Adding Code, Next: New Ports, Prev: Accessing The Source, Up: Additions -C.2.1 Adding New Features +C.2.2 Adding New Features ------------------------- You are free to add any new features you like to `gawk'. However, if you want your changes to be incorporated into the `gawk' distribution, there are several steps that you need to take in order to make it -possible for me to include your changes: +possible to include your changes: 1. Before building the new feature into `gawk' itself, consider writing it as an extension module (*note Dynamic Extensions::). @@ -20812,10 +20845,8 @@ possible for me to include your changes: document describes how GNU software should be written. If you haven't read it, please do so, preferably _before_ starting to modify `gawk'. (The `GNU Coding Standards' are available from the - GNU Project's `ftp' site, at - `ftp://ftp.gnu.org/gnu/GNUinfo/standards.text'. An HTML version, - suitable for reading with a WWW browser, is available at - `http://www.gnu.org/prep/standards_toc.html'. Texinfo, Info, and + GNU Project's web site + (http://www.gnu.org/prep/standards_toc.html). Texinfo, Info, and DVI versions are also available.) 4. Use the `gawk' coding style. The C code for `gawk' follows the @@ -20859,19 +20890,12 @@ possible for me to include your changes: character constant `'\0'' where appropriate, instead of `1' and `0'. - * Use the `ISALPHA', `ISDIGIT', etc. macros, instead of the - traditional lowercase versions; these macros are better - behaved for non-ASCII character sets. - * Provide one-line descriptive comments for each function. - * Do not use `#elif'. Many older Unix C compilers cannot handle - it. - - * Do not use the `alloca' function for allocating memory off + * Do not use the `alloca()' function for allocating memory off the stack. Its use causes more portability trouble than is worth the minor benefit of not having to free the storage. - Instead, use `malloc' and `free'. + Instead, use `malloc()' and `free()'. NOTE: If I have to reformat your code to follow the coding style used in `gawk', I may not bother to integrate your @@ -20883,7 +20907,7 @@ possible for me to include your changes: effect, or assign the copyright in your changes to the FSF. Both of these actions are easy to do and _many_ people have done so already. If you have questions, please contact me (*note Bugs::), - or <gnu@gnu.org>. + or <assign@gnu.org>. 6. Update the documentation. Along with your new code, please supply new sections and/or chapters for this Info file. If at all @@ -20897,13 +20921,11 @@ possible for me to include your changes: You will also have to sign paperwork for your documentation changes. - 7. Submit changes as context diffs or unified diffs. Use `diff -c -r - -N' or `diff -u -r -N' to compare the original `gawk' source tree - with your version. (I find context diffs to be more readable but - unified diffs are more compact.) I recommend using the GNU - version of `diff'. Send the output produced by either run of - `diff' to me when you submit your changes. (*Note Bugs::, for the - electronic mail information.) + 7. Submit changes as unified diffs. Use `diff -u -r -N' to compare + the original `gawk' source tree with your version. I recommend + using the GNU version of `diff'. Send the output produced by + either run of `diff' to me when you submit your changes. (*Note + Bugs::, for the electronic mail information.) Using this format makes it easy for me to apply your changes to the master version of the `gawk' source code (using `patch'). If I @@ -20922,7 +20944,7 @@ probably will not. File: gawk.info, Node: New Ports, Prev: Adding Code, Up: Additions -C.2.2 Porting `gawk' to a New Operating System +C.2.3 Porting `gawk' to a New Operating System ---------------------------------------------- If you want to port `gawk' to a new operating system, there are several @@ -20943,13 +20965,13 @@ steps: you comply with the GPL (*note Copying::). 3. A number of the files that come with `gawk' are maintained by other - people at the Free Software Foundation. Thus, you should not - change them unless it is for a very good reason; i.e., changes are - not out of the question, but changes to these files are - scrutinized extra carefully. The files are `getopt.h', - `getopt.c', `getopt1.c', `regex.h', `regex.c', `regcomp.c', - `regex_internal.c', `regex_internal.h', `regexec.c', `dfa.h', - `dfa.c', `install-sh', and `mkinstalldirs'. + people. Thus, you should not change them unless it is for a very + good reason; i.e., changes are not out of the question, but + changes to these files are scrutinized extra carefully. The files + are `dfa.c', `dfa.h', `getopt1.c', `getopt.c', `getopt.h', + `install-sh', `mkinstalldirs', `regcomp.c', `regex.c', + `regexec.c', `regexex.c', `regex.h', `regex_internal.c', and + `regex_internal.h'. 4. Be willing to continue to maintain the port. Non-Unix operating systems are supported by volunteers who maintain the code needed @@ -21011,23 +21033,24 @@ C.3 Adding New Built-in Functions to `gawk' Warning! Warning! The Robot - Beginning with `gawk' 3.1, 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 `dlopen' -and `dlsym' functions. This minor node describes how to write and use -dynamically loaded extensions for `gawk'. Experience with programming -in C or C++ is necessary when reading this minor node. + 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 minor node describes how to write and use dynamically +loaded extensions for `gawk'. Experience with programming in C or C++ +is necessary when reading this minor node. *Caution:* The facilities described in this minor node are very much subject to change in a future `gawk' release. Be aware that you may -have to re-do everything, perhaps from scratch, at some future time. +have to re-do everything, at some future time. *Caution:* If you have written your own dynamic extensions, be sure to recompile them for each new `gawk' release. There is no guarantee of binary compatibility between different releases, nor will there ever be such a guarantee. - NOTE: When `--sandbox' is specified, extensions are disabled. + NOTE: When `--sandbox' is specified, extensions are disabled + (*note Options::. * Menu: @@ -21072,6 +21095,11 @@ when writing extensions. The next minor node shows how they are used: may end up calling an internal `gawk' function. It also guarantees that the string is zero-terminated. +`void force_wstring(NODE *n)' + Similarly, this macro guarantees that a `NODE''s wide-string value + is current. It may end up calling an internal `gawk' function. + It also guarantees that the wide string is zero-terminated. + `size_t get_curfunc_arg_count(void)' This function returns the actual number of parameters passed to the current function. Inside the code of an extension this can be @@ -21079,11 +21107,9 @@ when writing extensions. The next minor node shows how they are used: `get_actual_argument'. If this value is greater than `nargs', the function was called incorrectly from the `awk' program. - *Caution:* This function is new as of `gawk' 3.1.4. - `nargs' Inside an extension function, this is the maximum number of - expected parameters, as set by the `make_builtin' function. + expected parameters, as set by the `make_builtin()' function. `n->stptr' `n->stlen' @@ -21093,9 +21119,15 @@ when writing extensions. The next minor node shows how they are used: `n->stptr[n->stlen]', assign `'\0'' to it, call the routine, and then restore the value. +`n->wstptr' +`n->wstlen' + The data and length of a `NODE''s wide-string value, respectively. + Use `force_wstring()' to make sure these values are current. + `n->type' - The type of the `NODE'. This is a C `enum'. Values should be - either `Node_var' or `Node_var_array' for function parameters. + The type of the `NODE'. This is a C `enum'. Values should be one + of `Node_var', `Node_var_new', or `Node_var_array' for function + parameters. `n->vname' The "variable name" of a node. This is not of much use inside @@ -21132,7 +21164,7 @@ when writing extensions. The next minor node shows how they are used: with `make_string' or `make_number'. Understanding of `gawk' memory management is helpful. -`void make_builtin(char *name, NODE *(*func)(NODE *), int count)' +`void make_builtin(const char *name, NODE *(*func)(NODE *), int count)' Register a C function pointed to by `func' as new built-in function `name'. `name' is a regular C string. `count' is the maximum number of arguments that the function takes. The function @@ -21159,17 +21191,11 @@ when writing extensions. The next minor node shows how they are used: If it wasn't, the return value is `NULL'. It is a fatal error if `optional' is `TRUE' but the argument was not provided. - *Caution:* This function is new as of `gawk' 3.1.4. - `get_scalar_argument(i, opt)' - This is a convenience macro that calls `get_actual_argument'. - - *Caution:* This macro is new as of `gawk' 3.1.4. + This is a convenience macro that calls `get_actual_argument()'. `get_array_argument(i, opt)' - This is a convenience macro that calls `get_actual_argument'. - - *Caution:* This macro is new as of `gawk' 3.1.4. + This is a convenience macro that calls `get_actual_argument()'. `void update_ERRNO(void)' This function is called from within a C extension function to set @@ -21182,8 +21208,6 @@ when writing extensions. The next minor node shows how they are used: of the C `errno' variable provided as the argument. It is provided as a convenience. - *Caution:* This function is new as of `gawk' 3.1.5. - `void register_deferred_variable(const char *name, NODE *(*load_func)(void))' This function is called to register a function to be called when a reference to an undefined variable with the given name is @@ -21191,31 +21215,29 @@ when writing extensions. The next minor node shows how they are used: variable exists already, so, unless the calling code is running at program startup, it should first check whether a variable of the given name already exists. The argument function must return a - pointer to a NODE containing the newly created variable. This + pointer to a `NODE' containing the newly created variable. This function is used to implement the builtin `ENVIRON' and `PROCINFO' variables, so you can refer to them for examples. - *Caution:* This function is new as of `gawk' 3.1.5. - `void register_open_hook(void *(*open_func)(IOBUF *))' This function is called to register a function to be called whenever a new data file is opened, leading to the creation of an - `IOBUF' structure in `iop_alloc'. After creating the new `IOBUF', - `iop_alloc' will call (in reverse order of registration, so the - last function registered is called first) each open hook until one - returns non-NULL. If any hook returns a non-NULL value, that - value is assigned to the `IOBUF''s `opaque' field (which will - presumably point to a structure containing additional state - associated with the input processing), and no further open hooks - are called. + `IOBUF' structure in `iop_alloc()'. After creating the new + `IOBUF', `iop_alloc()' will call (in reverse order of + registration, so the last function registered is called first) + each open hook until one returns non-`NULL'. If any hook returns + a non-`NULL' value, that value is assigned to the `IOBUF''s + `opaque' field (which will presumably point to a structure + containing additional state associated with the input processing), + and no further open hooks are called. The function called will most likely want to set the `IOBUF' - `get_record' method to indicate that future input records should + `get_record()' method to indicate that future input records should be retrieved by calling that method instead of using the standard `gawk' input processing. And the function will also probably want to set the `IOBUF' - `close_func' method to be called when the file is closed to clean + `close_func()' method to be called when the file is closed to clean up any state associated with the input. Finally, hook functions should be prepared to receive an `IOBUF' @@ -21228,57 +21250,11 @@ when writing extensions. The next minor node shows how they are used: implement the XML parser shared library extension. For more info, please look in `awk.h' and in `io.c'. - *Caution:* This function is new as of `gawk' 3.1.5. - An argument that is supposed to be an array needs to be handled with some extra code, in case the array being passed in is actually from a function parameter. - In versions of `gawk' up to and including 3.1.2, the following -boilerplate code shows how to do this: - - NODE *the_arg; - - the_arg = get_argument(tree, 2); /* assume need 3rd arg, 0-based */ - - /* if a parameter, get it off the stack */ - if (the_arg->type == Node_param_list) - the_arg = stack_ptr[the_arg->param_cnt]; - - /* parameter referenced an array, get it */ - if (the_arg->type == Node_array_ref) - the_arg = the_arg->orig_array; - - /* check type */ - if (the_arg->type != Node_var && the_arg->type != Node_var_array) - fatal("newfunc: third argument is not an array"); - - /* force it to be an array, if necessary, clear it */ - the_arg->type = Node_var_array; - assoc_clear(the_arg); - - For versions 3.1.3 and later, the internals changed. In particular, -the interface was actually _simplified_ drastically. The following -boilerplate code now suffices: - - NODE *the_arg; - - the_arg = get_argument(tree, 2); /* assume need 3rd arg, 0-based */ - - /* force it to be an array: */ - the_arg = get_array(the_arg); - - /* if necessary, clear it: */ - assoc_clear(the_arg); - - In version 3.1.4, the internals improved again, and became even -simpler: - - NODE *the_arg; - - the_arg = get_array_argument(tree, 2, FALSE); /* assume need 3rd arg, 0-based */ - - As of version 4.0, the internals changed again: + The following boilerplate code shows how to do this: NODE *the_arg; @@ -21307,11 +21283,11 @@ the symbol exists in the global scope. Something like this is enough: File: gawk.info, Node: Sample Library, Prev: Plugin License, Up: Dynamic Extensions -C.3.3 Directory and File Operation Built-ins --------------------------------------------- +C.3.3 Example: Directory and File Operation Built-ins +----------------------------------------------------- -Two useful functions that are not in `awk' are `chdir' (so that an -`awk' program can change its directory) and `stat' (so that an `awk' +Two useful functions that are not in `awk' are `chdir()' (so that an +`awk' program can change its directory) and `stat()' (so that an `awk' program can gather information about a file). This minor node implements these functions for `gawk' in an external extension library. @@ -21329,7 +21305,7 @@ C.3.3.1 Using `chdir' and `stat' This minor node shows how to use the new functions at the `awk' level once they've been integrated into the running `gawk' interpreter. -Using `chdir' is very straightforward. It takes one argument, the new +Using `chdir()' is very straightforward. It takes one argument, the new directory to change to: ... @@ -21345,9 +21321,9 @@ directory to change to: The return value is negative if the `chdir' failed, and `ERRNO' (*note Built-in Variables::) is set to a string indicating the error. - Using `stat' is a bit more complicated. The C `stat' function fills -in a structure that has a fair amount of information. The right way to -model this in `awk' is to fill in an associative array with the + Using `stat()' is a bit more complicated. The C `stat()' function +fills in a structure that has a fair amount of information. The right +way to model this in `awk' is to fill in an associative array with the appropriate information: file = "/home/arnold/.profile" @@ -21360,11 +21336,11 @@ appropriate information: } printf("size of %s is %d bytes\n", file, fdata["size"]) - The `stat' function always clears the data array, even if the `stat' -fails. It fills in the following elements: + The `stat()' function always clears the data array, even if the +`stat()' fails. It fills in the following elements: `"name"' - The name of the file that was `stat''ed. + The name of the file that was `stat()''ed. `"dev"' `"ino"' @@ -21447,8 +21423,8 @@ Elements::): File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops, Prev: Internal File Description, Up: Sample Library -C.3.3.2 C Code for `chdir' and `stat' -..................................... +C.3.3.2 C Code for `chdir()' and `stat()' +......................................... Here is the C code for these extensions. They were written for GNU/Linux. The code needs some more work for complete portability to @@ -21733,32 +21709,6 @@ Integrating the DBUG library Integrating Fred Fish's DBUG library would be helpful during development, but it's a lot of work to do. - Following is a list of probable improvements that will make `gawk' -perform better: - - *FIXME: NEXT ED:* remove this item. awka and mawk do these - respectively. - -Compilation of `awk' programs - `gawk' uses a Bison (YACC-like) parser to convert the script given - it into a syntax tree; the syntax tree is then executed by a - simple recursive evaluator. This method incurs a lot of overhead, - since the recursive evaluator performs many procedure calls to do - even the simplest things. - - It should be possible for `gawk' to convert the script's parse tree - into a C program which the user would then compile, using the - normal C compiler and a special `gawk' library to provide all the - needed functions (regexps, fields, associative arrays, type - coercion, and so on). - - An easier possibility might be for an intermediate phase of `gawk' - to convert the parse tree into a linear byte code form like the - one used in GNU Emacs Lisp. The recursive evaluator would then be - replaced by a straight line byte code interpreter that would be - intermediate in speed between running a compiled program and doing - what `gawk' does now. - Finally, the programs in the test suite could use documenting in this Info file. @@ -24486,18 +24436,18 @@ Index * arguments, command-line, invoking awk: Command Line. (line 6) * arguments, in function calls: Function Calls. (line 16) * arguments, processing: Getopt Function. (line 6) -* arguments, retrieving: Internals. (line 111) +* arguments, retrieving: Internals. (line 120) * arithmetic operators: Arithmetic Ops. (line 6) * arrays: Arrays. (line 6) * arrays, as parameters to functions: Pass By Value/Reference. (line 47) * arrays, associative: Array Intro. (line 50) -* arrays, associative, clearing: Internals. (line 66) +* arrays, associative, clearing: Internals. (line 75) * arrays, associative, library functions and: Library Names. (line 57) * arrays, deleting entire contents: Delete. (line 39) * arrays, elements, assigning: Assigning Elements. (line 6) * arrays, elements, deleting: Delete. (line 6) -* arrays, elements, installing: Internals. (line 70) +* arrays, elements, installing: Internals. (line 79) * arrays, elements, order of: Scanning an Array. (line 48) * arrays, elements, referencing: Reference to Elements. (line 6) @@ -24531,8 +24481,8 @@ Index * assignment operators, evaluation order: Assignment Ops. (line 111) * assignment operators, lvalues/rvalues: Assignment Ops. (line 32) * assignments as filenames: Ignoring Assigns. (line 6) -* assoc_clear internal function: Internals. (line 66) -* assoc_lookup internal function: Internals. (line 70) +* assoc_clear() internal function: Internals. (line 75) +* assoc_lookup() internal function: Internals. (line 79) * associative arrays: Array Intro. (line 50) * asterisk (*), * operator, as multiplication operator: Precedence. (line 55) @@ -24778,7 +24728,7 @@ Index * characters, transliterating: Translate Program. (line 6) * characters, values of as numbers: Ordinal Functions. (line 6) * Chassell, Robert J.: Acknowledgments. (line 32) -* chdir function, implementing in gawk: Sample Library. (line 6) +* chdir() function, implementing in gawk: Sample Library. (line 6) * chem utility: Glossary. (line 145) * chr() user-defined function: Ordinal Functions. (line 16) * clear debugger command: Breakpoint Control. (line 33) @@ -24797,7 +24747,7 @@ Index * close() function, two-way pipes and: Two-way I/O. (line 77) * Close, Diane <1>: Contributors. (line 21) * Close, Diane: Manual History. (line 39) -* close_func input method: Internals. (line 162) +* close_func() input method: Internals. (line 161) * collating elements: Character Lists. (line 70) * collating symbols: Character Lists. (line 77) * Colombo, Antonio: Acknowledgments. (line 59) @@ -24890,7 +24840,7 @@ Index * cut utility: Cut Program. (line 6) * cut.awk program: Cut Program. (line 45) * Cygwin build of gawk: Cygwin. (line 6) -* d debugger command (alias for break): Breakpoint Control. (line 58) +* d debugger command (alias for break): Breakpoint Control. (line 60) * d.c., See dark corner: Conventions. (line 37) * dark corner <1>: Glossary. (line 187) * dark corner <2>: Truth Values. (line 24) @@ -24965,16 +24915,16 @@ Index * debugger commands, condition: Breakpoint Control. (line 51) * debugger commands, continue: Dgawk Execution Control. (line 33) -* debugger commands, d (delete): Breakpoint Control. (line 58) -* debugger commands, delete: Breakpoint Control. (line 58) -* debugger commands, disable: Breakpoint Control. (line 63) +* debugger commands, d (delete): Breakpoint Control. (line 60) +* debugger commands, delete: Breakpoint Control. (line 60) +* debugger commands, disable: Breakpoint Control. (line 65) * debugger commands, display: Viewing And Changing Data. (line 8) * debugger commands, down: Dgawk Stack. (line 21) * debugger commands, dump: Miscellaneous Dgawk Commands. (line 9) -* debugger commands, e (enable): Breakpoint Control. (line 67) -* debugger commands, enable: Breakpoint Control. (line 67) +* debugger commands, e (enable): Breakpoint Control. (line 69) +* debugger commands, enable: Breakpoint Control. (line 69) * debugger commands, end: Dgawk Execution Control. (line 10) * debugger commands, eval: Viewing And Changing Data. @@ -24984,16 +24934,16 @@ Index (line 39) * debugger commands, frame: Dgawk Stack. (line 25) * debugger commands, h (help): Miscellaneous Dgawk Commands. - (line 71) + (line 68) * debugger commands, help: Miscellaneous Dgawk Commands. - (line 71) + (line 68) * debugger commands, i (info): Dgawk Info. (line 12) -* debugger commands, ignore: Breakpoint Control. (line 81) +* debugger commands, ignore: Breakpoint Control. (line 83) * debugger commands, info: Dgawk Info. (line 12) * debugger commands, l (list): Miscellaneous Dgawk Commands. - (line 77) + (line 74) * debugger commands, list: Miscellaneous Dgawk Commands. - (line 77) + (line 74) * debugger commands, n (next): Dgawk Execution Control. (line 43) * debugger commands, next: Dgawk Execution Control. @@ -25011,9 +24961,9 @@ Index * debugger commands, printf: Viewing And Changing Data. (line 54) * debugger commands, q (quit): Miscellaneous Dgawk Commands. - (line 104) + (line 101) * debugger commands, quit: Miscellaneous Dgawk Commands. - (line 104) + (line 101) * debugger commands, r (run): Dgawk Execution Control. (line 62) * debugger commands, return: Dgawk Execution Control. @@ -25032,10 +24982,10 @@ Index (line 68) * debugger commands, stepi: Dgawk Execution Control. (line 76) -* debugger commands, t (tbreak): Breakpoint Control. (line 84) -* debugger commands, tbreak: Breakpoint Control. (line 84) +* debugger commands, t (tbreak): Breakpoint Control. (line 86) +* debugger commands, tbreak: Breakpoint Control. (line 86) * debugger commands, trace: Miscellaneous Dgawk Commands. - (line 113) + (line 110) * debugger commands, u (until): Dgawk Execution Control. (line 83) * debugger commands, undisplay: Viewing And Changing Data. @@ -25056,7 +25006,7 @@ Index * Deifik, Scott <1>: Bugs. (line 70) * Deifik, Scott <2>: Contributors. (line 53) * Deifik, Scott: Acknowledgments. (line 59) -* delete debugger command: Breakpoint Control. (line 58) +* delete debugger command: Breakpoint Control. (line 60) * delete statement: Delete. (line 6) * deleting elements in arrays: Delete. (line 6) * deleting entire arrays: Delete. (line 39) @@ -25131,7 +25081,7 @@ Index (line 6) * directories, searching <1>: Igawk Program. (line 364) * directories, searching: AWKPATH Variable. (line 6) -* disable debugger command: Breakpoint Control. (line 63) +* disable debugger command: Breakpoint Control. (line 65) * display debugger command: Viewing And Changing Data. (line 8) * division: Arithmetic Ops. (line 44) @@ -25154,9 +25104,9 @@ Index * DuBois, John: Acknowledgments. (line 59) * dump debugger command: Miscellaneous Dgawk Commands. (line 9) -* dupnode internal function: Internals. (line 87) +* dupnode() internal function: Internals. (line 96) * dupword.awk program: Dupword Program. (line 31) -* e debugger command (alias for break): Breakpoint Control. (line 67) +* e debugger command (alias for break): Breakpoint Control. (line 69) * EBCDIC: Ordinal Functions. (line 45) * egrep utility <1>: Egrep Program. (line 6) * egrep utility: Character Lists. (line 23) @@ -25172,7 +25122,7 @@ Index * empty pattern: Empty. (line 6) * empty strings, See null strings: Regexp Field Splitting. (line 43) -* enable debugger command: Breakpoint Control. (line 67) +* enable debugger command: Breakpoint Control. (line 69) * end debugger command: Dgawk Execution Control. (line 10) * END pattern: BEGIN/END. (line 6) @@ -25195,7 +25145,7 @@ Index * endgrent() user-defined function: Group Functions. (line 219) * endpwent() function (C library): Passwd Functions. (line 211) * endpwent() user-defined function: Passwd Functions. (line 214) -* ENVIRON variable <1>: Internals. (line 149) +* ENVIRON variable <1>: Internals. (line 150) * ENVIRON variable: Auto-set. (line 60) * environment variables: Auto-set. (line 60) * epoch, definition of: Glossary. (line 229) @@ -25204,7 +25154,7 @@ Index * equals sign (=), == operator: Comparison Operators. (line 11) * EREs (Extended Regular Expressions): Character Lists. (line 23) -* ERRNO variable <1>: Internals. (line 136) +* ERRNO variable <1>: Internals. (line 139) * ERRNO variable <2>: Auto-set. (line 72) * ERRNO variable: Getline. (line 19) * error handling: Special FD. (line 15) @@ -25379,8 +25329,9 @@ Index * FNR variable, changing: Auto-set. (line 200) * for statement: For Statement. (line 6) * for statement, in arrays: Scanning an Array. (line 20) -* force_number internal function: Internals. (line 27) -* force_string internal function: Internals. (line 32) +* force_number() internal function: Internals. (line 27) +* force_string() internal function: Internals. (line 32) +* force_wstring() internal function: Internals. (line 37) * format specifiers, mixing regular with positional specifiers: Printf Ordering. (line 57) * format specifiers, printf statement: Control Letters. (line 6) @@ -25455,7 +25406,7 @@ Index * functions, names of <1>: Definition Syntax. (line 20) * functions, names of: Arrays. (line 18) * functions, recursive: Definition Syntax. (line 73) -* functions, return values, setting: Internals. (line 136) +* functions, return values, setting: Internals. (line 139) * functions, string-translation: I18N Functions. (line 6) * functions, undefined: Pass By Value/Reference. (line 71) @@ -25475,7 +25426,7 @@ Index * gawk, break statement in: Break Statement. (line 51) * gawk, built-in variables and: Built-in Variables. (line 14) * gawk, character classes and: Character Lists. (line 91) -* gawk, coding style in: Adding Code. (line 32) +* gawk, coding style in: Adding Code. (line 30) * gawk, command-line options: GNU Regexp Operators. (line 70) * gawk, comparison operators and: Comparison Operators. @@ -25511,7 +25462,6 @@ Index * gawk, internals: Internals. (line 6) * gawk, internationalization and, See internationalization: Internationalization. (line 13) -* gawk, interpreter, adding code to <1>: Future Extensions. (line 90) * gawk, interpreter, adding code to: Using Internal File Ops. (line 6) * gawk, interval expressions and: Regexp Operators. (line 138) @@ -25545,12 +25495,12 @@ Index * gensub() function (gawk): Using Constant Regexps. (line 43) * gensub() function (gawk), escape processing: Gory Details. (line 6) -* get_actual_argument internal function: Internals. (line 116) -* get_argument internal function: Internals. (line 111) -* get_array_argument internal macro: Internals. (line 131) -* get_curfunc_arg_count internal function: Internals. (line 37) -* get_record input method: Internals. (line 162) -* get_scalar_argument internal macro: Internals. (line 126) +* get_actual_argument() internal function: Internals. (line 125) +* get_argument() internal function: Internals. (line 120) +* get_array_argument() internal macro: Internals. (line 136) +* get_curfunc_arg_count() internal function: Internals. (line 42) +* get_record() input method: Internals. (line 161) +* get_scalar_argument() internal macro: Internals. (line 133) * getaddrinfo() function (C library): TCP/IP Networking. (line 37) * getgrent() function (C library): Group Functions. (line 6) * getgrent() user-defined function: Group Functions. (line 6) @@ -25614,7 +25564,7 @@ Index * gsub() function, arguments of: String Functions. (line 434) * gsub() function, escape processing: Gory Details. (line 6) * h debugger command (alias for help): Miscellaneous Dgawk Commands. - (line 71) + (line 68) * Hankerson, Darrel <1>: Contributors. (line 58) * Hankerson, Darrel: Acknowledgments. (line 59) * Haque, John <1>: Contributors. (line 98) @@ -25623,7 +25573,7 @@ Index * Hartholz, Marshall: Acknowledgments. (line 37) * Hasegawa, Isamu: Contributors. (line 89) * help debugger command: Miscellaneous Dgawk Commands. - (line 71) + (line 68) * hexadecimal numbers: Nondecimal-numbers. (line 6) * hexadecimal values, enabling interpretation of: Options. (line 166) * histsort.awk program: History Sorting. (line 25) @@ -25643,7 +25593,7 @@ Index * if statement: Regexp Usage. (line 19) * if statement, actions, changing: Ranges. (line 25) * igawk.sh program: Igawk Program. (line 124) -* ignore debugger command: Breakpoint Control. (line 81) +* ignore debugger command: Breakpoint Control. (line 83) * IGNORECASE variable <1>: User-modified. (line 82) * IGNORECASE variable: Case-sensitivity. (line 26) * IGNORECASE variable, array sorting and: Array Sorting. (line 69) @@ -25717,8 +25667,8 @@ Index * interpreted programs: Basic High Level. (line 15) * interval expressions: Regexp Operators. (line 115) * inventory-shipped file: Sample Data Files. (line 32) -* IOBUF internal structure: Internals. (line 162) -* iop_alloc internal function: Internals. (line 162) +* IOBUF internal structure: Internals. (line 161) +* iop_alloc() internal function: Internals. (line 161) * ISO: Glossary. (line 356) * ISO 8859-1: Glossary. (line 137) * ISO Latin-1: Glossary. (line 137) @@ -25745,7 +25695,7 @@ Index * Knights, jedi: Undocumented. (line 6) * Kwok, Conrad: Contributors. (line 37) * l debugger command (alias for list): Miscellaneous Dgawk Commands. - (line 77) + (line 74) * labels.awk program: Labels Program. (line 51) * languages, data-driven: Basic High Level. (line 85) * LC_ALL locale category: Explaining gettext. (line 120) @@ -25820,7 +25770,7 @@ Index * Linux <2>: I18N Example. (line 55) * Linux: Manual History. (line 28) * list debugger command: Miscellaneous Dgawk Commands. - (line 77) + (line 74) * local variables: Variable Scope. (line 6) * locale categories: Explaining gettext. (line 80) * locale decimal point character: Options. (line 222) @@ -25845,9 +25795,9 @@ Index * lvalues/rvalues: Assignment Ops. (line 32) * mailing labels, printing: Labels Program. (line 6) * mailing list, GNITS: Acknowledgments. (line 51) -* make_builtin internal function: Internals. (line 97) -* make_number internal function: Internals. (line 82) -* make_string internal function: Internals. (line 77) +* make_builtin() internal function: Internals. (line 106) +* make_number() internal function: Internals. (line 91) +* make_string() internal function: Internals. (line 86) * mark parity: Ordinal Functions. (line 45) * marked string extraction (internationalization): String Extraction. (line 6) @@ -25862,7 +25812,7 @@ Index * matching, null strings: Gory Details. (line 96) * mawk program: Other Versions. (line 34) * McPhee, Patrick: Contributors. (line 95) -* memory, releasing: Internals. (line 92) +* memory, releasing: Internals. (line 101) * message object files: Explaining gettext. (line 41) * message object files, converting from portable object files: I18N Example. (line 62) @@ -25884,7 +25834,7 @@ Index * namespace issues <1>: Library Names. (line 6) * namespace issues: Arrays. (line 18) * namespace issues, functions: Definition Syntax. (line 20) -* nargs internal variable: Internals. (line 46) +* nargs internal variable: Internals. (line 49) * nawk utility: Names. (line 17) * negative zero: Unexpected Results. (line 28) * NetBSD: Glossary. (line 580) @@ -25924,7 +25874,7 @@ Index (line 49) * noassign.awk program: Ignoring Assigns. (line 15) * NODE internal type: Internals. (line 23) -* nodes, duplicating: Internals. (line 87) +* nodes, duplicating: Internals. (line 96) * not Boolean-logic operator: Boolean Ops. (line 6) * NR variable <1>: Auto-set. (line 118) * NR variable: Records. (line 6) @@ -25945,7 +25895,7 @@ Index * number sign (#), #! (executable scripts), portability issues with: Executable Scripts. (line 6) * number sign (#), commenting: Comments. (line 6) -* numbers: Internals. (line 82) +* numbers: Internals. (line 91) * numbers, as array subscripts: Numeric Array Subscripts. (line 6) * numbers, as values of characters: Ordinal Functions. (line 6) @@ -26048,7 +25998,7 @@ Index (line 36) * P1003.1 POSIX standard: Glossary. (line 427) * P1003.2 POSIX standard: Glossary. (line 427) -* parameters, number of: Internals. (line 46) +* parameters, number of: Internals. (line 49) * parentheses (): Regexp Operators. (line 78) * parentheses (), pgawk program: Profiling. (line 141) * password file: Passwd Functions. (line 16) @@ -26080,7 +26030,7 @@ Index (line 6) * pipes, input: Getline/Pipe. (line 6) * pipes, output: Redirection. (line 57) -* Pitts, Dave <1>: Bugs. (line 74) +* Pitts, Dave <1>: Bugs. (line 73) * Pitts, Dave: Acknowledgments. (line 59) * plus sign (+): Regexp Operators. (line 101) * plus sign (+), + operator: Precedence. (line 52) @@ -26212,7 +26162,7 @@ Index * PROCINFO array <1>: Group Functions. (line 6) * PROCINFO array <2>: Passwd Functions. (line 6) * PROCINFO array: Auto-set. (line 123) -* PROCINFO variable: Internals. (line 149) +* PROCINFO variable: Internals. (line 150) * profiling awk programs: Profiling. (line 6) * profiling awk programs, dynamically: Profiling. (line 174) * profiling gawk, See pgawk program: Profiling. (line 6) @@ -26240,7 +26190,7 @@ Index * programming, concepts: Basic Concepts. (line 6) * pwcat program: Passwd Functions. (line 23) * q debugger command (alias for quit): Miscellaneous Dgawk Commands. - (line 104) + (line 101) * QSE Awk: Other Versions. (line 128) * question mark (?) <1>: GNU Regexp Operators. (line 59) @@ -26248,7 +26198,7 @@ Index * question mark (?), ?: operator: Precedence. (line 92) * QuikTrim Awk: Other Versions. (line 121) * quit debugger command: Miscellaneous Dgawk Commands. - (line 104) + (line 101) * QUIT signal (MS-Windows): Profiling. (line 207) * quoting <1>: Comments. (line 27) * quoting <2>: Long. (line 26) @@ -26266,7 +26216,7 @@ Index * random numbers, seed of: Numeric Functions. (line 63) * range expressions: Character Lists. (line 6) * range patterns: Ranges. (line 6) -* Rankin, Pat <1>: Bugs. (line 73) +* Rankin, Pat <1>: Bugs. (line 72) * Rankin, Pat <2>: Contributors. (line 35) * Rankin, Pat <3>: Assignment Ops. (line 100) * Rankin, Pat: Acknowledgments. (line 59) @@ -26300,8 +26250,8 @@ Index * regexp constants, slashes vs. quotes: Computed Regexps. (line 28) * regexp constants, vs. string constants: Computed Regexps. (line 38) * regexp, See regular expressions: Regexp. (line 6) -* register_deferred_variable internal function: Internals. (line 149) -* register_open_hook internal function: Internals. (line 162) +* register_deferred_variable() internal function: Internals. (line 150) +* register_open_hook() internal function: Internals. (line 161) * regular expressions: Regexp. (line 6) * regular expressions as field separators: Field Separators. (line 50) * regular expressions, anchors in: Regexp Operators. (line 22) @@ -26500,7 +26450,7 @@ Index * standard input <1>: Special FD. (line 6) * standard input: Read Terminal. (line 6) * standard output: Special FD. (line 6) -* stat function, implementing in gawk: Sample Library. (line 6) +* stat() function, implementing in gawk: Sample Library. (line 6) * statements, compound, control statements and: Statements. (line 10) * statements, control, in actions: Statements. (line 6) * statements, multiple: Statements/Lines. (line 90) @@ -26508,8 +26458,8 @@ Index (line 68) * stepi debugger command: Dgawk Execution Control. (line 76) -* stlen internal variable: Internals. (line 50) -* stptr internal variable: Internals. (line 50) +* stlen internal variable: Internals. (line 53) +* stptr internal variable: Internals. (line 53) * stream editors <1>: Simple Sed. (line 6) * stream editors: Field Splitting Summary. (line 47) @@ -26520,7 +26470,7 @@ Index (line 6) * string operators: Concatenation. (line 9) * string-matching operators: Regexp Usage. (line 19) -* strings: Internals. (line 77) +* strings: Internals. (line 86) * strings, converting: Conversion. (line 6) * strings, converting, numbers to <1>: Bitwise Functions. (line 107) * strings, converting, numbers to: User-modified. (line 28) @@ -26560,8 +26510,8 @@ Index (line 148) * system() function: I/O Functions. (line 64) * systime() function (gawk): Time Functions. (line 64) -* t debugger command (alias for tbreak): Breakpoint Control. (line 84) -* tbreak debugger command: Breakpoint Control. (line 84) +* t debugger command (alias for tbreak): Breakpoint Control. (line 86) +* tbreak debugger command: Breakpoint Control. (line 86) * Tcl: Library Names. (line 57) * TCP/IP: TCP/IP Networking. (line 6) * TCP/IP, support for: Special Network. (line 6) @@ -26569,7 +26519,7 @@ Index * tee.awk program: Tee Program. (line 26) * terminating records: Records. (line 112) * testbits.awk program: Bitwise Functions. (line 68) -* Texinfo <1>: Adding Code. (line 99) +* Texinfo <1>: Adding Code. (line 90) * Texinfo <2>: Distribution contents. (line 68) * Texinfo <3>: Extract Program. (line 12) @@ -26608,7 +26558,7 @@ Index * toupper() function: String Functions. (line 501) * tr utility: Translate Program. (line 6) * trace debugger command: Miscellaneous Dgawk Commands. - (line 113) + (line 110) * translate.awk program: Translate Program. (line 55) * troubleshooting, --non-decimal-data option: Options. (line 169) * troubleshooting, == operator: Comparison Operators. @@ -26650,7 +26600,7 @@ Index * trunc-mod operation: Arithmetic Ops. (line 66) * truth values: Truth Values. (line 6) * type conversion: Conversion. (line 21) -* type internal variable: Internals. (line 58) +* type internal variable: Internals. (line 66) * u debugger command (alias for until): Dgawk Execution Control. (line 83) * undefined functions: Pass By Value/Reference. @@ -26675,15 +26625,15 @@ Index (line 72) * Unix, awk scripts and: Executable Scripts. (line 6) * UNIXROOT variable, on OS/2 systems: PC Using. (line 17) -* unref internal function: Internals. (line 92) +* unref() internal function: Internals. (line 101) * unsigned integers: Basic Data Typing. (line 28) * until debugger command: Dgawk Execution Control. (line 83) * unwatch debugger command: Viewing And Changing Data. (line 84) * up debugger command: Dgawk Stack. (line 33) -* update_ERRNO internal function: Internals. (line 136) -* update_ERRNO_saved internal function: Internals. (line 141) +* update_ERRNO() internal function: Internals. (line 139) +* update_ERRNO_saved() internal function: Internals. (line 144) * user database, reading: Passwd Functions. (line 6) * user-defined, functions: User-defined. (line 6) * user-defined, functions, counts: Profiling. (line 132) @@ -26735,7 +26685,7 @@ Index * vertical bar (|), || operator <1>: Precedence. (line 89) * vertical bar (|), || operator: Boolean Ops. (line 57) * Vinschen, Corinna: Acknowledgments. (line 59) -* vname internal variable: Internals. (line 62) +* vname internal variable: Internals. (line 71) * w debugger command (alias for watch): Viewing And Changing Data. (line 67) * w utility: Constant Size. (line 22) @@ -26756,7 +26706,6 @@ Index * whitespace, functions, calling: Calling Built-in. (line 10) * whitespace, newlines as: Options. (line 205) * Williams, Kent: Contributors. (line 37) -* Woehlke, Matthew <1>: Bugs. (line 72) * Woehlke, Matthew: Contributors. (line 75) * Woods, John: Contributors. (line 28) * word boundaries, matching: GNU Regexp Operators. @@ -26769,8 +26718,10 @@ Index * words, counting: Wc Program. (line 6) * words, duplicate, searching for: Dupword Program. (line 6) * words, usage counts, generating: Word Sorting. (line 6) +* wstlen internal variable: Internals. (line 61) +* wstptr internal variable: Internals. (line 61) * xgettext utility: String Extraction. (line 13) -* XML: Internals. (line 162) +* XML: Internals. (line 161) * XOR bitwise operation: Bitwise Functions. (line 6) * xor() function (gawk): Bitwise Functions. (line 54) * Zaretskii, Eli <1>: Bugs. (line 70) @@ -26806,404 +26757,405 @@ Index Tag Table: Node: Top1340 -Node: Foreword29910 -Node: Preface34230 -Ref: Preface-Footnote-137182 -Ref: Preface-Footnote-237288 -Node: History37520 -Node: Names39752 -Ref: Names-Footnote-141229 -Node: This Manual41301 -Ref: This Manual-Footnote-146199 -Node: Conventions46299 -Node: Manual History48358 -Ref: Manual History-Footnote-151536 -Ref: Manual History-Footnote-251577 -Node: How To Contribute51651 -Node: Acknowledgments52795 -Node: Getting Started57064 -Node: Running gawk59443 -Node: One-shot60629 -Node: Read Terminal61854 -Ref: Read Terminal-Footnote-163504 -Ref: Read Terminal-Footnote-263778 -Node: Long63949 -Node: Executable Scripts65325 -Ref: Executable Scripts-Footnote-167186 -Ref: Executable Scripts-Footnote-267288 -Node: Comments67739 -Node: Quoting70107 -Node: DOS Quoting74724 -Node: Sample Data Files75399 -Node: Very Simple78431 -Node: Two Rules83028 -Node: More Complex85175 -Ref: More Complex-Footnote-188105 -Node: Statements/Lines88185 -Ref: Statements/Lines-Footnote-192543 -Node: Other Features92808 -Node: When93677 -Node: Invoking Gawk95820 -Node: Command Line97205 -Node: Options97988 -Ref: Options-Footnote-1111334 -Node: Other Arguments111359 -Node: Naming Standard Input114022 -Node: Environment Variables114986 -Node: AWKPATH Variable115430 -Ref: AWKPATH Variable-Footnote-1118167 -Node: Other Environment Variables118427 -Node: Exit Status120775 -Node: Include Files121450 -Node: Obsolete124841 -Node: Undocumented125527 -Node: Regexp125768 -Node: Regexp Usage127220 -Node: Escape Sequences129246 -Node: Regexp Operators134989 -Ref: Regexp Operators-Footnote-1142161 -Ref: Regexp Operators-Footnote-2142308 -Node: Character Lists142406 -Ref: table-char-classes144181 -Node: GNU Regexp Operators146806 -Node: Case-sensitivity150519 -Ref: Case-sensitivity-Footnote-1153474 -Ref: Case-sensitivity-Footnote-2153709 -Node: Leftmost Longest153817 -Node: Computed Regexps155018 -Node: Locales158435 -Node: Reading Files161977 -Node: Records163918 -Ref: Records-Footnote-1172590 -Node: Fields172627 -Ref: Fields-Footnote-1175659 -Node: Nonconstant Fields175745 -Node: Changing Fields177947 -Node: Field Separators183232 -Node: Default Field Splitting185861 -Node: Regexp Field Splitting186978 -Node: Single Character Fields190328 -Node: Command Line Field Separator191379 -Node: Field Splitting Summary194818 -Ref: Field Splitting Summary-Footnote-1198004 -Node: Constant Size198105 -Node: Splitting By Content202667 -Ref: Splitting By Content-Footnote-1206393 -Node: Multiple Line206433 -Ref: Multiple Line-Footnote-1212280 -Node: Getline212459 -Node: Plain Getline214687 -Node: Getline/Variable216776 -Node: Getline/File217917 -Node: Getline/Variable/File219239 -Ref: Getline/Variable/File-Footnote-1220838 -Node: Getline/Pipe220925 -Node: Getline/Variable/Pipe223473 -Node: Getline/Coprocess224580 -Node: Getline/Variable/Coprocess225823 -Node: Getline Notes226537 -Node: Getline Summary228479 -Ref: table-getline-variants228763 -Node: Command line directories229668 -Node: Printing230293 -Node: Print231924 -Node: Print Examples233261 -Node: Output Separators236045 -Node: OFMT237804 -Node: Printf239162 -Node: Basic Printf240068 -Node: Control Letters241605 -Node: Format Modifiers245417 -Node: Printf Examples251428 -Node: Redirection254143 -Node: Special Files261121 -Node: Special FD261654 -Ref: Special FD-Footnote-1265229 -Node: Special Network265303 -Node: Special Caveats266158 -Node: Close Files And Pipes266952 -Ref: Close Files And Pipes-Footnote-1273896 -Ref: Close Files And Pipes-Footnote-2274044 -Node: Expressions274194 -Node: Values275263 -Node: Constants275939 -Node: Scalar Constants276619 -Ref: Scalar Constants-Footnote-1277478 -Node: Nondecimal-numbers277660 -Node: Regexp Constants280719 -Node: Using Constant Regexps281194 -Node: Variables284199 -Node: Using Variables284854 -Node: Assignment Options286581 -Node: Conversion288462 -Ref: table-locale-affects293836 -Ref: Conversion-Footnote-1294460 -Node: All Operators294569 -Node: Arithmetic Ops295199 -Node: Concatenation297698 -Ref: Concatenation-Footnote-1300491 -Node: Assignment Ops300610 -Ref: table-assign-ops305598 -Node: Increment Ops306999 -Node: Truth Values and Conditions310477 -Node: Truth Values311560 -Node: Typing and Comparison312608 -Node: Variable Typing313397 -Ref: Variable Typing-Footnote-1317294 -Node: Comparison Operators317416 -Ref: table-relational-ops317826 -Node: POSIX String Comparison321375 -Ref: POSIX String Comparison-Footnote-1322332 -Node: Boolean Ops322470 -Ref: Boolean Ops-Footnote-1326548 -Node: Conditional Exp326639 -Node: Function Calls328371 -Node: Precedence331930 -Node: Patterns and Actions335583 -Node: Pattern Overview336637 -Node: Regexp Patterns338303 -Node: Expression Patterns338846 -Node: Ranges342420 -Node: BEGIN/END345386 -Node: Using BEGIN/END346136 -Ref: Using BEGIN/END-Footnote-1348867 -Node: I/O And BEGIN/END348981 -Node: Empty351250 -Node: BEGINFILE/ENDFILE351584 -Node: Using Shell Variables354409 -Node: Action Overview356688 -Node: Statements359045 -Node: If Statement360904 -Node: While Statement362403 -Node: Do Statement364447 -Node: For Statement365603 -Node: Switch Statement368755 -Node: Break Statement370852 -Node: Continue Statement372828 -Node: Next Statement374529 -Node: Nextfile Statement376911 -Node: Exit Statement379429 -Node: Built-in Variables381760 -Node: User-modified382855 -Ref: User-modified-Footnote-1390856 -Node: Auto-set390918 -Ref: Auto-set-Footnote-1399901 -Node: ARGC and ARGV400106 -Node: Arrays403865 -Node: Array Basics405436 -Node: Array Intro406147 -Node: Reference to Elements410465 -Node: Assigning Elements412735 -Node: Array Example413226 -Node: Scanning an Array414958 -Node: Delete417235 -Ref: Delete-Footnote-1419633 -Node: Numeric Array Subscripts419690 -Node: Uninitialized Subscripts421873 -Node: Multi-dimensional423501 -Node: Multi-scanning426592 -Node: Array Sorting428176 -Ref: Array Sorting-Footnote-1431374 -Node: Arrays of Arrays431568 -Node: Functions435730 -Node: Built-in436552 -Node: Calling Built-in437566 -Node: Numeric Functions439542 -Ref: Numeric Functions-Footnote-1443251 -Ref: Numeric Functions-Footnote-2443587 -Ref: Numeric Functions-Footnote-3443635 -Node: String Functions443904 -Ref: String Functions-Footnote-1465703 -Ref: String Functions-Footnote-2465832 -Ref: String Functions-Footnote-3466080 -Node: Gory Details466167 -Ref: table-sub-escapes467824 -Ref: table-posix-sub469138 -Ref: table-gensub-escapes470038 -Node: I/O Functions471209 -Ref: I/O Functions-Footnote-1477906 -Node: Time Functions478053 -Ref: Time Functions-Footnote-1488920 -Ref: Time Functions-Footnote-2488988 -Ref: Time Functions-Footnote-3489146 -Ref: Time Functions-Footnote-4489257 -Ref: Time Functions-Footnote-5489369 -Ref: Time Functions-Footnote-6489596 -Node: Bitwise Functions489862 -Ref: table-bitwise-ops490420 -Ref: Bitwise Functions-Footnote-1494580 -Node: I18N Functions494764 -Node: User-defined496394 -Node: Definition Syntax497198 -Ref: Definition Syntax-Footnote-1501828 -Node: Function Example501897 -Node: Function Caveats504491 -Node: Calling A Function504912 -Node: Variable Scope506001 -Node: Pass By Value/Reference507929 -Node: Return Statement511369 -Node: Dynamic Typing514311 -Node: Indirect Calls515048 -Node: Internationalization524733 -Node: I18N and L10N526161 -Node: Explaining gettext526847 -Ref: Explaining gettext-Footnote-1531909 -Ref: Explaining gettext-Footnote-2532092 -Node: Programmer i18n532257 -Node: Translator i18n536520 -Node: String Extraction537313 -Ref: String Extraction-Footnote-1538274 -Node: Printf Ordering538360 -Ref: Printf Ordering-Footnote-1541144 -Node: I18N Portability541208 -Ref: I18N Portability-Footnote-1543657 -Node: I18N Example543720 -Ref: I18N Example-Footnote-1546355 -Node: Gawk I18N546427 -Node: Advanced Features546996 -Node: Nondecimal Data548315 -Node: Two-way I/O549876 -Ref: Two-way I/O-Footnote-1555290 -Node: TCP/IP Networking555367 -Node: Profiling558139 -Node: Library Functions565539 -Ref: Library Functions-Footnote-1568509 -Node: Library Names568680 -Ref: Library Names-Footnote-1572151 -Ref: Library Names-Footnote-2572371 -Node: General Functions572457 -Node: Nextfile Function573520 -Node: Strtonum Function577901 -Node: Assert Function580852 -Node: Round Function584178 -Node: Cliff Random Function585719 -Node: Ordinal Functions586735 -Ref: Ordinal Functions-Footnote-1589805 -Ref: Ordinal Functions-Footnote-2590057 -Node: Join Function590273 -Ref: Join Function-Footnote-1592044 -Node: Gettimeofday Function592244 -Node: Data File Management595959 -Node: Filetrans Function596591 -Node: Rewind Function600828 -Node: File Checking602281 -Node: Empty Files603375 -Node: Ignoring Assigns605605 -Node: Getopt Function607158 -Ref: Getopt Function-Footnote-1618483 -Node: Passwd Functions618686 -Ref: Passwd Functions-Footnote-1627674 -Node: Group Functions627762 -Node: Sample Programs635842 -Node: Running Examples636507 -Node: Clones637235 -Node: Cut Program638358 -Node: Egrep Program648199 -Ref: Egrep Program-Footnote-1655970 -Node: Id Program656080 -Node: Split Program659696 -Ref: Split Program-Footnote-1663215 -Node: Tee Program663343 -Node: Uniq Program666146 -Node: Wc Program673569 -Ref: Wc Program-Footnote-1677833 -Node: Miscellaneous Programs678033 -Node: Dupword Program679153 -Node: Alarm Program681184 -Node: Translate Program685906 -Ref: Translate Program-Footnote-1690285 -Ref: Translate Program-Footnote-2690513 -Node: Labels Program690647 -Ref: Labels Program-Footnote-1694018 -Node: Word Sorting694102 -Node: History Sorting698447 -Node: Extract Program700285 -Ref: Extract Program-Footnote-1707711 -Node: Simple Sed707839 -Node: Igawk Program710901 -Ref: Igawk Program-Footnote-1725935 -Ref: Igawk Program-Footnote-2726136 -Node: Signature Program726274 -Node: Debugger727354 -Node: Debugging728265 -Node: Debugging Concepts728579 -Node: Debugging Terms730435 -Node: Awk Debugging732980 -Node: Sample dgawk session733872 -Node: dgawk invocation734364 -Node: Finding The Bug735546 -Node: List of Debugger Commands742105 -Node: Breakpoint Control743416 -Node: Dgawk Execution Control746742 -Node: Viewing And Changing Data750093 -Node: Dgawk Stack753402 -Node: Dgawk Info754862 -Node: Miscellaneous Dgawk Commands758810 -Node: Readline Support764524 -Node: Dgawk Limitations765351 -Node: Language History767490 -Node: V7/SVR3.1768867 -Node: SVR4771162 -Node: POSIX772607 -Node: BTL774862 -Node: POSIX/GNU776266 -Node: Contributors781396 -Node: Installation785341 -Node: Gawk Distribution786235 -Node: Getting786719 -Node: Extracting787545 -Node: Distribution contents789223 -Node: Unix Installation794088 -Node: Quick Installation794705 -Node: Additional Configuration Options796595 -Node: Configuration Philosophy798072 -Node: Non-Unix Installation800414 -Node: PC Installation800872 -Node: PC Binary Installation802171 -Node: PC Compiling804019 -Node: PC Testing807425 -Node: PC Using808249 -Node: Cygwin812426 -Node: MSYS813423 -Node: VMS Installation813937 -Node: VMS Compilation814541 -Node: VMS Installation Details816118 -Node: VMS Running817748 -Node: VMS POSIX819345 -Node: VMS Old Gawk820643 -Node: Bugs821115 -Node: Other Versions825045 -Node: Notes830493 -Node: Compatibility Mode831185 -Node: Additions831968 -Node: Adding Code832718 -Node: New Ports838770 -Node: Dynamic Extensions842902 -Node: Internals844283 -Node: Plugin License854688 -Node: Sample Library855322 -Node: Internal File Description855986 -Node: Internal File Ops859681 -Ref: Internal File Ops-Footnote-1864557 -Node: Using Internal File Ops864705 -Node: Future Extensions866730 -Node: Basic Concepts870767 -Node: Basic High Level871524 -Ref: Basic High Level-Footnote-1875643 -Node: Basic Data Typing875837 -Node: Floating Point Issues880274 -Node: String Conversion Precision881357 -Ref: String Conversion Precision-Footnote-1883051 -Node: Unexpected Results883160 -Node: POSIX Floating Point Problems884986 -Ref: POSIX Floating Point Problems-Footnote-1888685 -Node: Glossary888723 -Node: Copying912358 -Node: GNU Free Documentation License949915 -Node: next-edition975059 -Node: unresolved975411 -Node: revision975911 -Node: consistency976334 -Node: Index979687 +Node: Foreword29975 +Node: Preface34295 +Ref: Preface-Footnote-137247 +Ref: Preface-Footnote-237353 +Node: History37585 +Node: Names39817 +Ref: Names-Footnote-141294 +Node: This Manual41366 +Ref: This Manual-Footnote-146264 +Node: Conventions46364 +Node: Manual History48423 +Ref: Manual History-Footnote-151601 +Ref: Manual History-Footnote-251642 +Node: How To Contribute51716 +Node: Acknowledgments52860 +Node: Getting Started57129 +Node: Running gawk59508 +Node: One-shot60694 +Node: Read Terminal61919 +Ref: Read Terminal-Footnote-163569 +Ref: Read Terminal-Footnote-263843 +Node: Long64014 +Node: Executable Scripts65390 +Ref: Executable Scripts-Footnote-167251 +Ref: Executable Scripts-Footnote-267353 +Node: Comments67804 +Node: Quoting70172 +Node: DOS Quoting74789 +Node: Sample Data Files75464 +Node: Very Simple78496 +Node: Two Rules83093 +Node: More Complex85240 +Ref: More Complex-Footnote-188170 +Node: Statements/Lines88250 +Ref: Statements/Lines-Footnote-192608 +Node: Other Features92873 +Node: When93742 +Node: Invoking Gawk95885 +Node: Command Line97270 +Node: Options98053 +Ref: Options-Footnote-1111399 +Node: Other Arguments111424 +Node: Naming Standard Input114087 +Node: Environment Variables115051 +Node: AWKPATH Variable115495 +Ref: AWKPATH Variable-Footnote-1118232 +Node: Other Environment Variables118492 +Node: Exit Status120840 +Node: Include Files121515 +Node: Obsolete124906 +Node: Undocumented125592 +Node: Regexp125833 +Node: Regexp Usage127285 +Node: Escape Sequences129311 +Node: Regexp Operators135054 +Ref: Regexp Operators-Footnote-1142226 +Ref: Regexp Operators-Footnote-2142373 +Node: Character Lists142471 +Ref: table-char-classes144246 +Node: GNU Regexp Operators146871 +Node: Case-sensitivity150584 +Ref: Case-sensitivity-Footnote-1153539 +Ref: Case-sensitivity-Footnote-2153774 +Node: Leftmost Longest153882 +Node: Computed Regexps155083 +Node: Locales158500 +Node: Reading Files162042 +Node: Records163983 +Ref: Records-Footnote-1172655 +Node: Fields172692 +Ref: Fields-Footnote-1175724 +Node: Nonconstant Fields175810 +Node: Changing Fields178012 +Node: Field Separators183297 +Node: Default Field Splitting185926 +Node: Regexp Field Splitting187043 +Node: Single Character Fields190393 +Node: Command Line Field Separator191444 +Node: Field Splitting Summary194883 +Ref: Field Splitting Summary-Footnote-1198069 +Node: Constant Size198170 +Node: Splitting By Content202732 +Ref: Splitting By Content-Footnote-1206458 +Node: Multiple Line206498 +Ref: Multiple Line-Footnote-1212345 +Node: Getline212524 +Node: Plain Getline214752 +Node: Getline/Variable216841 +Node: Getline/File217982 +Node: Getline/Variable/File219304 +Ref: Getline/Variable/File-Footnote-1220903 +Node: Getline/Pipe220990 +Node: Getline/Variable/Pipe223538 +Node: Getline/Coprocess224645 +Node: Getline/Variable/Coprocess225888 +Node: Getline Notes226602 +Node: Getline Summary228544 +Ref: table-getline-variants228828 +Node: Command line directories229733 +Node: Printing230358 +Node: Print231989 +Node: Print Examples233326 +Node: Output Separators236110 +Node: OFMT237869 +Node: Printf239227 +Node: Basic Printf240133 +Node: Control Letters241670 +Node: Format Modifiers245482 +Node: Printf Examples251493 +Node: Redirection254208 +Node: Special Files261186 +Node: Special FD261719 +Ref: Special FD-Footnote-1265294 +Node: Special Network265368 +Node: Special Caveats266223 +Node: Close Files And Pipes267017 +Ref: Close Files And Pipes-Footnote-1273961 +Ref: Close Files And Pipes-Footnote-2274109 +Node: Expressions274259 +Node: Values275328 +Node: Constants276004 +Node: Scalar Constants276684 +Ref: Scalar Constants-Footnote-1277543 +Node: Nondecimal-numbers277725 +Node: Regexp Constants280784 +Node: Using Constant Regexps281259 +Node: Variables284264 +Node: Using Variables284919 +Node: Assignment Options286646 +Node: Conversion288527 +Ref: table-locale-affects293901 +Ref: Conversion-Footnote-1294525 +Node: All Operators294634 +Node: Arithmetic Ops295264 +Node: Concatenation297763 +Ref: Concatenation-Footnote-1300556 +Node: Assignment Ops300675 +Ref: table-assign-ops305663 +Node: Increment Ops307064 +Node: Truth Values and Conditions310542 +Node: Truth Values311625 +Node: Typing and Comparison312673 +Node: Variable Typing313462 +Ref: Variable Typing-Footnote-1317359 +Node: Comparison Operators317481 +Ref: table-relational-ops317891 +Node: POSIX String Comparison321440 +Ref: POSIX String Comparison-Footnote-1322397 +Node: Boolean Ops322535 +Ref: Boolean Ops-Footnote-1326613 +Node: Conditional Exp326704 +Node: Function Calls328436 +Node: Precedence331995 +Node: Patterns and Actions335648 +Node: Pattern Overview336702 +Node: Regexp Patterns338368 +Node: Expression Patterns338911 +Node: Ranges342485 +Node: BEGIN/END345451 +Node: Using BEGIN/END346201 +Ref: Using BEGIN/END-Footnote-1348932 +Node: I/O And BEGIN/END349046 +Node: Empty351315 +Node: BEGINFILE/ENDFILE351649 +Node: Using Shell Variables354474 +Node: Action Overview356753 +Node: Statements359110 +Node: If Statement360969 +Node: While Statement362468 +Node: Do Statement364512 +Node: For Statement365668 +Node: Switch Statement368820 +Node: Break Statement370917 +Node: Continue Statement372893 +Node: Next Statement374594 +Node: Nextfile Statement376976 +Node: Exit Statement379494 +Node: Built-in Variables381825 +Node: User-modified382920 +Ref: User-modified-Footnote-1390921 +Node: Auto-set390983 +Ref: Auto-set-Footnote-1399966 +Node: ARGC and ARGV400171 +Node: Arrays403930 +Node: Array Basics405501 +Node: Array Intro406212 +Node: Reference to Elements410530 +Node: Assigning Elements412800 +Node: Array Example413291 +Node: Scanning an Array415023 +Node: Delete417300 +Ref: Delete-Footnote-1419698 +Node: Numeric Array Subscripts419755 +Node: Uninitialized Subscripts421938 +Node: Multi-dimensional423566 +Node: Multi-scanning426657 +Node: Array Sorting428241 +Ref: Array Sorting-Footnote-1431439 +Node: Arrays of Arrays431633 +Node: Functions435795 +Node: Built-in436617 +Node: Calling Built-in437631 +Node: Numeric Functions439607 +Ref: Numeric Functions-Footnote-1443316 +Ref: Numeric Functions-Footnote-2443652 +Ref: Numeric Functions-Footnote-3443700 +Node: String Functions443969 +Ref: String Functions-Footnote-1465768 +Ref: String Functions-Footnote-2465897 +Ref: String Functions-Footnote-3466145 +Node: Gory Details466232 +Ref: table-sub-escapes467889 +Ref: table-posix-sub469203 +Ref: table-gensub-escapes470103 +Node: I/O Functions471274 +Ref: I/O Functions-Footnote-1477971 +Node: Time Functions478118 +Ref: Time Functions-Footnote-1488985 +Ref: Time Functions-Footnote-2489053 +Ref: Time Functions-Footnote-3489211 +Ref: Time Functions-Footnote-4489322 +Ref: Time Functions-Footnote-5489434 +Ref: Time Functions-Footnote-6489661 +Node: Bitwise Functions489927 +Ref: table-bitwise-ops490485 +Ref: Bitwise Functions-Footnote-1494645 +Node: I18N Functions494829 +Node: User-defined496459 +Node: Definition Syntax497263 +Ref: Definition Syntax-Footnote-1501893 +Node: Function Example501962 +Node: Function Caveats504556 +Node: Calling A Function504977 +Node: Variable Scope506066 +Node: Pass By Value/Reference507994 +Node: Return Statement511434 +Node: Dynamic Typing514376 +Node: Indirect Calls515113 +Node: Internationalization524798 +Node: I18N and L10N526226 +Node: Explaining gettext526912 +Ref: Explaining gettext-Footnote-1531974 +Ref: Explaining gettext-Footnote-2532157 +Node: Programmer i18n532322 +Node: Translator i18n536585 +Node: String Extraction537378 +Ref: String Extraction-Footnote-1538339 +Node: Printf Ordering538425 +Ref: Printf Ordering-Footnote-1541209 +Node: I18N Portability541273 +Ref: I18N Portability-Footnote-1543722 +Node: I18N Example543785 +Ref: I18N Example-Footnote-1546420 +Node: Gawk I18N546492 +Node: Advanced Features547061 +Node: Nondecimal Data548380 +Node: Two-way I/O549941 +Ref: Two-way I/O-Footnote-1555355 +Node: TCP/IP Networking555432 +Node: Profiling558204 +Node: Library Functions565604 +Ref: Library Functions-Footnote-1568574 +Node: Library Names568745 +Ref: Library Names-Footnote-1572216 +Ref: Library Names-Footnote-2572436 +Node: General Functions572522 +Node: Nextfile Function573585 +Node: Strtonum Function577966 +Node: Assert Function580917 +Node: Round Function584243 +Node: Cliff Random Function585784 +Node: Ordinal Functions586800 +Ref: Ordinal Functions-Footnote-1589870 +Ref: Ordinal Functions-Footnote-2590122 +Node: Join Function590338 +Ref: Join Function-Footnote-1592109 +Node: Gettimeofday Function592309 +Node: Data File Management596024 +Node: Filetrans Function596656 +Node: Rewind Function600893 +Node: File Checking602346 +Node: Empty Files603440 +Node: Ignoring Assigns605670 +Node: Getopt Function607223 +Ref: Getopt Function-Footnote-1618548 +Node: Passwd Functions618751 +Ref: Passwd Functions-Footnote-1627739 +Node: Group Functions627827 +Node: Sample Programs635907 +Node: Running Examples636572 +Node: Clones637300 +Node: Cut Program638423 +Node: Egrep Program648264 +Ref: Egrep Program-Footnote-1656035 +Node: Id Program656145 +Node: Split Program659761 +Ref: Split Program-Footnote-1663280 +Node: Tee Program663408 +Node: Uniq Program666211 +Node: Wc Program673634 +Ref: Wc Program-Footnote-1677898 +Node: Miscellaneous Programs678098 +Node: Dupword Program679218 +Node: Alarm Program681249 +Node: Translate Program685971 +Ref: Translate Program-Footnote-1690350 +Ref: Translate Program-Footnote-2690578 +Node: Labels Program690712 +Ref: Labels Program-Footnote-1694083 +Node: Word Sorting694167 +Node: History Sorting698512 +Node: Extract Program700350 +Ref: Extract Program-Footnote-1707776 +Node: Simple Sed707904 +Node: Igawk Program710966 +Ref: Igawk Program-Footnote-1726000 +Ref: Igawk Program-Footnote-2726201 +Node: Signature Program726339 +Node: Debugger727419 +Node: Debugging728330 +Node: Debugging Concepts728644 +Node: Debugging Terms730500 +Node: Awk Debugging733045 +Node: Sample dgawk session733937 +Node: dgawk invocation734429 +Node: Finding The Bug735611 +Node: List of Debugger Commands742095 +Node: Breakpoint Control743406 +Node: Dgawk Execution Control746882 +Node: Viewing And Changing Data750233 +Node: Dgawk Stack753542 +Node: Dgawk Info755002 +Node: Miscellaneous Dgawk Commands758950 +Node: Readline Support764378 +Node: Dgawk Limitations765205 +Node: Language History767344 +Node: V7/SVR3.1768721 +Node: SVR4771016 +Node: POSIX772461 +Node: BTL774716 +Node: POSIX/GNU776120 +Node: Contributors781250 +Node: Installation785195 +Node: Gawk Distribution786089 +Node: Getting786573 +Node: Extracting787399 +Node: Distribution contents789077 +Node: Unix Installation793942 +Node: Quick Installation794559 +Node: Additional Configuration Options796449 +Node: Configuration Philosophy797926 +Node: Non-Unix Installation800268 +Node: PC Installation800726 +Node: PC Binary Installation802025 +Node: PC Compiling803873 +Node: PC Testing807279 +Node: PC Using808103 +Node: Cygwin812280 +Node: MSYS813277 +Node: VMS Installation813791 +Node: VMS Compilation814395 +Node: VMS Installation Details815972 +Node: VMS Running817602 +Node: VMS POSIX819199 +Node: VMS Old Gawk820497 +Node: Bugs820969 +Node: Other Versions824814 +Node: Notes830262 +Node: Compatibility Mode830954 +Node: Additions831737 +Node: Accessing The Source832549 +Node: Adding Code833972 +Node: New Ports839520 +Node: Dynamic Extensions843633 +Node: Internals844993 +Node: Plugin License854112 +Node: Sample Library854746 +Node: Internal File Description855432 +Node: Internal File Ops859139 +Ref: Internal File Ops-Footnote-1864023 +Node: Using Internal File Ops864171 +Node: Future Extensions866196 +Node: Basic Concepts869033 +Node: Basic High Level869790 +Ref: Basic High Level-Footnote-1873909 +Node: Basic Data Typing874103 +Node: Floating Point Issues878540 +Node: String Conversion Precision879623 +Ref: String Conversion Precision-Footnote-1881317 +Node: Unexpected Results881426 +Node: POSIX Floating Point Problems883252 +Ref: POSIX Floating Point Problems-Footnote-1886951 +Node: Glossary886989 +Node: Copying910624 +Node: GNU Free Documentation License948181 +Node: next-edition973325 +Node: unresolved973677 +Node: revision974177 +Node: consistency974600 +Node: Index977953 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 70207459..be33ae87 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -105,6 +105,19 @@ DONE: @end macro @end ifnottex +@c For HTML, spell out email addresses, to avoid problems with +@c address harvesters for spammers. +@ifhtml +@macro EMAIL{real,spelled} +``\spelled\'' +@end macro +@end ifhtml +@ifnothtml +@macro EMAIL{real,spelled} +@email{\real\} +@end macro +@end ifnothtml + @set FN file name @set FFN File Name @set DF data file @@ -672,6 +685,7 @@ particular records in a file and perform operations upon them. * Compatibility Mode:: How to disable certain @command{gawk} extensions. * Additions:: Making Additions To @command{gawk}. +* Accessing The Source:: Accessing the Git repository. * Adding Code:: Adding code to the main body of @command{gawk}. * New Ports:: Porting @command{gawk} to a new operating @@ -24759,15 +24773,14 @@ not to be mentioned): @example dgawk> @kbd{p @@alast} -@print{} alast["4"] = string ("wonderful") -@print{} alast["5"] = string ("program!") @print{} alast["1"] = string ("awk") @print{} alast["2"] = string ("is") @print{} alast["3"] = string ("a") +@print{} alast["4"] = string ("wonderful") +@print{} alast["5"] = string ("program!") @end example -Ignoring the ordering of the elements for now (a @command{dgawk} internals -issue), it looks like we got this far OK. Let's take another step +It looks like we got this far OK. Let's take another step or two: @example @@ -24921,7 +24934,9 @@ Add a condition to existing breakpoint or watchpoint @var{n}. The condition is an @command{awk} expression that @command{dgawk} evaluates whenever the breakpoint or watchpoint is reached. If the condition is true, then @command{dgawk} stops execution and prompts for a command. Otherwise, -@command{dgawk} continues executing the program. +@command{dgawk} continues executing the program. If the condition expression is +not specified, any existing condition is removed; i.e., the breakpoint or +watchpoint is made unconditional. @cindex debugger commands, @code{d} (@code{delete}) @cindex debugger commands, @code{delete} @@ -24951,7 +24966,7 @@ Optionally, you can specify how to enable the breakpoint: @c nested table @table @code @item del -Enable the breakpoint(s) tempoarily, then delete it when +Enable the breakpoint(s) temporarily, then delete it when the program stops at the breakpoint. @item once @@ -25409,55 +25424,52 @@ partial dump of Davide Brini's obfuscated code dgawk> @kbd{dump} @print{} # BEGIN @print{} -@print{} [ 2:0x1d4355f0] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] -@print{} [ 3:0x1d435710] Op_push_i : "~" [MALLOC|PERM|STRING|STRCUR] -@print{} [ 3:0x1d4357c0] Op_push_i : "~" [MALLOC|PERM|STRING|STRCUR] -@print{} [ 3:0x1d435790] Op_match : -@print{} [ 3:0x1d435680] Op_push_lhs : O [do_reference = FALSE] -@print{} [ 3:0x1d4356b0] Op_assign : -@print{} [ :0x1d4356e0] Op_pop : -@print{} [ 4:0x1d4358c0] Op_push_i : "==" [MALLOC|PERM|STRING|STRCUR] -@print{} [ 4:0x1d435970] Op_push_i : "==" [MALLOC|PERM|STRING|STRCUR] -@print{} [ 4:0x1d435940] Op_equal : -@print{} [ 4:0x1d435810] Op_push_lhs : o [do_reference = FALSE] -@print{} [ 4:0x1d435860] Op_assign : -@print{} [ :0x1d435890] Op_pop : -@print{} [ 5:0x1d435a70] Op_push : o -@print{} [ 5:0x1d435a40] Op_plus_i : 0 [MALLOC|NUMCUR|NUMBER] -@print{} [ 5:0x1d4359c0] Op_push_lhs : o [do_reference = TRUE] -@print{} [ 5:0x1d435910] Op_assign_plus : -@print{} [ :0x1d435a10] Op_pop : -@print{} [ 6:0x1d435b50] Op_push : O -@print{} [ 6:0x1d435b80] Op_push_i : "" [MALLOC|PERM|STRING|STRCUR] -@print{} [ :0x1d435c60] Op_no_op : -@print{} [ 6:0x1d435c30] Op_push : O -@print{} [ :0x1d435c90] Op_concat : [expr_count = 3] -@print{} [ 6:0x1d435ad0] Op_push_lhs : x [do_reference = FALSE] -@print{} [ 6:0x1d435aa0] Op_assign : -@print{} [ :0x1d435b00] Op_pop : -@print{} [ 7:0x1d435c00] Op_push_loop : [target_continue = 0x1d435bd0] [target_break = 0x1d435fc0] -@print{} [ 7:0x1d435bd0] Op_push_lhs : X [do_reference = TRUE] -@print{} [ 7:0x1d435cc0] Op_postincrement : -@print{} [ 7:0x1d435d70] Op_push : x -@print{} [ 7:0x1d435e00] Op_push : o -@print{} [ 7:0x1d435da0] Op_plus : -@print{} [ 7:0x1d435e60] Op_push : o -@print{} [ 7:0x1d435e30] Op_plus : -@print{} [ 7:0x1d435d20] Op_leq : -@print{} [ :0x1d435cf0] Op_jmp_false : [target_jmp = 0x1d435fc0] -@print{} [ 8:0x1d435f40] Op_push_i : "%c" [MALLOC|PERM|STRING|STRCUR] -@print{} [ :0x1d435ff0] Op_no_op : -@print{} [ 8:0x1d435dd0] Op_push_lhs : c [do_reference = FALSE] -@print{} [ 8:0x1d435e90] Op_assign_concat : -@print{} [ :0x1d435ec0] Op_pop : -@print{} [ :0x1d435f90] Op_jmp : [target_jmp = 0x1d435bd0] -@print{} [ :0x1d435fc0] Op_pop_loop : +@print{} [ 2:0x89faef4] Op_rule : [in_rule = BEGIN] [source_file = brini.awk] +@print{} [ 3:0x89fa428] Op_push_i : "~" [PERM|STRING|STRCUR] +@print{} [ 3:0x89fa464] Op_push_i : "~" [PERM|STRING|STRCUR] +@print{} [ 3:0x89fa450] Op_match : +@print{} [ 3:0x89fa3ec] Op_store_var : O [do_reference = FALSE] +@print{} [ 4:0x89fa48c] Op_push_i : "==" [PERM|STRING|STRCUR] +@print{} [ 4:0x89fa4c8] Op_push_i : "==" [PERM|STRING|STRCUR] +@print{} [ 4:0x89fa4b4] Op_equal : +@print{} [ 4:0x89fa400] Op_store_var : o [do_reference = FALSE] +@print{} [ 5:0x89fa4f0] Op_push : o +@print{} [ 5:0x89fa4dc] Op_plus_i : 0 [PERM|NUMCUR|NUMBER] +@print{} [ 5:0x89fa414] Op_push_lhs : o [do_reference = TRUE] +@print{} [ 5:0x89fa4a0] Op_assign_plus : +@print{} [ :0x89fa478] Op_pop : +@print{} [ 6:0x89fa540] Op_push : O +@print{} [ 6:0x89fa554] Op_push_i : "" [PERM|STRING|STRCUR] +@print{} [ :0x89fa5a4] Op_no_op : +@print{} [ 6:0x89fa590] Op_push : O +@print{} [ :0x89fa5b8] Op_concat : [expr_count = 3] [concat_flag = 0] +@print{} [ 6:0x89fa518] Op_store_var : x [do_reference = FALSE] +@print{} [ 7:0x89fa504] Op_push_loop : [target_continue = 0x89fa568] [target_break = 0x89fa680] +@print{} [ 7:0x89fa568] Op_push_lhs : X [do_reference = TRUE] +@print{} [ 7:0x89fa52c] Op_postincrement : +@print{} [ 7:0x89fa5e0] Op_push : x +@print{} [ 7:0x89fa61c] Op_push : o +@print{} [ 7:0x89fa5f4] Op_plus : +@print{} [ 7:0x89fa644] Op_push : o +@print{} [ 7:0x89fa630] Op_plus : +@print{} [ 7:0x89fa5cc] Op_leq : +@print{} [ :0x89fa57c] Op_jmp_false : [target_jmp = 0x89fa680] +@print{} [ 7:0x89fa694] Op_push_i : "%c" [PERM|STRING|STRCUR] +@print{} [ :0x89fa6d0] Op_no_op : +@print{} [ 7:0x89fa608] Op_assign_concat : c +@print{} [ :0x89fa6a8] Op_jmp : [target_jmp = 0x89fa568] +@print{} [ :0x89fa680] Op_pop_loop : @print{} @print{} @dots{} @print{} -@print{} [ 9:0x1d435f10] Op_K_printf : [expr_count = 17] [redir_type = Op_illegal] -@print{} [ :0x1d435180] Op_no_op : -@print{} [ :0x1d435240] Op_exit : [exit_value = 0] +@print{} [ 8:0x89fa658] Op_K_printf : [expr_count = 17] [redir_type = ""] +@print{} [ :0x89fa374] Op_no_op : +@print{} [ :0x89fa3d8] Op_atexit : +@print{} [ :0x89fa6bc] Op_stop : +@print{} [ :0x89fa39c] Op_no_op : +@print{} [ :0x89fa3b0] Op_after_beginfile : +@print{} [ :0x89fa388] Op_no_op : +@print{} [ :0x89fa3c4] Op_after_endfile : dgawk> @end smallexample @@ -27550,18 +27562,13 @@ You can get this information with the command @samp{gawk --version}. @cindex @code{bug-gawk@@gnu.org} bug reporting address @cindex email address for bug reports, @code{bug-gawk@@gnu.org} @cindex bug reports, email address, @code{bug-gawk@@gnu.org} -Once you have a precise problem, send email to @email{bug-gawk@@gnu.org}. +Once you have a precise problem, send email to +@EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. @cindex Robbins, Arnold Using this address automatically sends a carbon copy of your mail to me. If necessary, I can be reached directly at -@c Don't put real address into web pages, to avoid robots, spiders, etc. -@ifhtml -``arnold at skeeve dot com.'' -@end ifhtml -@ifnothtml -@email{arnold@@skeeve.com}. -@end ifnothtml +@EMAIL{arnold@@skeeve.com,arnold at skeeve dot com}. The bug reporting address is preferred since the email list is archived at the GNU Project. @emph{All email should be in English, since that is my native language.} @@ -27577,7 +27584,8 @@ Really. @quotation NOTE Many distributions of GNU/Linux and the various BSD-based operating systems have their own bug reporting systems. If you report a bug using your distribution's -bug reporting system, @emph{please} also send a copy to @email{bug-gawk@@gnu.org}. +bug reporting system, @emph{please} also send a copy to +@EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org}. This is for two reasons. First, while some distributions forward bug reports ``upstream'' to the GNU mailing list, many don't, so there is a good @@ -27601,27 +27609,24 @@ authoritative if it conflicts with this @value{DOCUMENT}. The people maintaining the non-Unix ports of @command{gawk} are as follows: -@multitable {Tandem (POSIX-compliant)} {123456789012345678901234567890123456789001234567890} +@multitable {MS-Windows using MINGW} {123456789012345678901234567890123456789001234567890} @cindex Zaretskii, Eli @cindex Deifik, Scott -@item MS-Windows using MINGW @tab Eli Zaretskii, @email{eliz@@gnu.org}. -@item @tab Scott Deifik, @email{scottd.mail@@sbcglobal.net}. +@item MS-Windows using MINGW @tab Eli Zaretskii, @EMAIL{eliz@@gnu.org,eliz at gnu dot org}. +@item @tab Scott Deifik, @EMAIL{scottd.mail@@sbcglobal.net,scottd dot mail at sbcglobal dot net}. @cindex Buening, Andreas -@item OS/2 @tab Andreas Buening, @email{andreas.buening@@nexgo.de} - -@cindex Woehlke, Matthew -@item Tandem (POSIX-compliant) @tab Matthew Woehlke, @email{mw_triad@@users.sourceforge.net} +@item OS/2 @tab Andreas Buening, @EMAIL{andreas.buening@@nexgo.de,andreas dot buening at nexgo dot de}. @cindex Rankin, Pat -@item VMS @tab Pat Rankin, @email{rankin@@pactechdata.com}. +@item VMS @tab Pat Rankin, @EMAIL{rankin@@pactechdata.com,rankin at pactechdata dot com}. @cindex Pitts, Dave -@item z/OS (OS/390) @tab Dave Pitts, @email{pitts@@cozx.com}. +@item z/OS (OS/390) @tab Dave Pitts, @EMAIL{dpitts@@cozx.com,dpitts at cozx dot com}. @end multitable If your bug is also reproducible under Unix, please send a copy of your -report to the @email{bug-gawk@@gnu.org} email list as well. +report to the @EMAIL{bug-gawk@@gnu.org,bug-gawk at gnu dot org} email list as well. @c ENDOFRANGE dbugg @c ENDOFRANGE tblgawb @@ -27891,12 +27896,53 @@ This @value{SECTION} discusses the ways you might want to change @command{gawk} as well as any considerations you should bear in mind. @menu +* Accessing The Source:: Accessing the Git repository. * Adding Code:: Adding code to the main body of @command{gawk}. * New Ports:: Porting @command{gawk} to a new operating system. @end menu +@node Accessing The Source +@appendixsubsec Accessing The @command{gawk} Git Repository + +As @command{gawk} is Free Software, the source code is always available +@ref{Gawk Distribution}, describes how to get and build the formal, +released versions of @command{gawk}. + +However, if you want to modify @command{gawk} and contribute back your +changes, you will probably wish to work with the development version. +To do so, you will need to access the @command{gawk} source code +repository. The code is maintained using the +@uref{http://git-scm.com/, Git distributed version control system}. +You will need to install it if your system doesn't have it. +Once you have done so, use the command: + +@example +git clone git://git.savannah.gnu.org/gawk.git +@end example + +@noindent +This will clone the @command{gawk} repository. If you are behind a +firewall that will not allow you to use the Git native protocol, you +can still access the repository using: + +@example +git clone http://git.savannah.gnu.org/r/gawk.git +@end example + +Once you have made changes, you can use @samp{git diff} to produce a +patch, and send that to the @command{gawk} maintainer; see @ref{Bugs} +for how to do that. + +Finally, if you cannot install Git (e.g., if it hasn't been ported +yet to your operating system), you can use the Git--CVS gateway +to check out a copy using CVS, as follows: + +@example +cvs -d:pserver:anonymous@@pserver.git.sv.gnu.org:/gawk.git co -d gawk master +@end example + @node Adding Code @appendixsubsec Adding New Features @@ -27909,7 +27955,7 @@ as well as any considerations you should bear in mind. You are free to add any new features you like to @command{gawk}. However, if you want your changes to be incorporated into the @command{gawk} distribution, there are several steps that you need to take in order to -make it possible for me to include your changes: +make it possible to include your changes: @enumerate 1 @item @@ -27937,12 +27983,7 @@ This document describes how GNU software should be written. If you haven't read it, please do so, preferably @emph{before} starting to modify @command{gawk}. (The @cite{GNU Coding Standards} are available from the GNU Project's -@command{ftp} -site, at -@uref{ftp://ftp.gnu.org/gnu/GNUinfo/standards.text}. -An HTML version, suitable for reading with a WWW browser, is -available at -@uref{http://www.gnu.org/prep/standards_toc.html}. +@uref{http://www.gnu.org/prep/standards_toc.html, web site}. Texinfo, Info, and DVI versions are also available.) @cindex @command{gawk}, coding style in @@ -27998,20 +28039,13 @@ and the character constant @code{'\0'} where appropriate, instead of @code{1} and @code{0}. @item -Use the @code{ISALPHA}, @code{ISDIGIT}, etc.@: macros, instead of the -traditional lowercase versions; these macros are better behaved for -non-ASCII character sets. - -@item Provide one-line descriptive comments for each function. @item -Do not use @samp{#elif}. Many older Unix C compilers cannot handle it. - -@item -Do not use the @code{alloca} function for allocating memory off the stack. -Its use causes more portability trouble than is worth the minor benefit of not having -to free the storage. Instead, use @code{malloc} and @code{free}. +Do not use the @code{alloca()} function for allocating memory off the +stack. Its use causes more portability trouble than is worth the minor +benefit of not having to free the storage. Instead, use @code{malloc()} +and @code{free()}. @end itemize @quotation NOTE @@ -28027,7 +28061,7 @@ effect, or assign the copyright in your changes to the FSF. Both of these actions are easy to do and @emph{many} people have done so already. If you have questions, please contact me (@pxref{Bugs}), -or @email{gnu@@gnu.org}. +or @EMAIL{assign@@gnu.org,assign at gnu dot org}. @cindex Texinfo @item @@ -28043,11 +28077,9 @@ If possible, please update the @command{man} page as well. You will also have to sign paperwork for your documentation changes. @item -Submit changes as context diffs or unified diffs. -Use @samp{diff -c -r -N} or @samp{diff -u -r -N} to compare +Submit changes as unified diffs. +Use @samp{diff -u -r -N} to compare the original @command{gawk} source tree with your version. -(I find context diffs to be more readable but unified diffs are -more compact.) I recommend using the GNU version of @command{diff}. Send the output produced by either run of @command{diff} to me when you submit your changes. @@ -28108,13 +28140,13 @@ with the GPL @item A number of the files that come with @command{gawk} are maintained by other -people at the Free Software Foundation. Thus, you should not change them +people. Thus, you should not change them unless it is for a very good reason; i.e., changes are not out of the question, but changes to these files are scrutinized extra carefully. -The files are @file{getopt.h}, @file{getopt.c}, @file{getopt1.c}, -@file{regex.h}, @file{regex.c}, @file{regcomp.c}, @file{regex_internal.c}, -@file{regex_internal.h}, @file{regexec.c}, @file{dfa.h}, @file{dfa.c}, -@file{install-sh}, and @file{mkinstalldirs}. +The files are @file{dfa.c}, @file{dfa.h}, @file{getopt1.c}, @file{getopt.c}, +@file{getopt.h}, @file{install-sh}, @file{mkinstalldirs}, @file{regcomp.c}, +@file{regex.c}, @file{regexec.c}, @file{regexex.c}, @file{regex.h}, +@file{regex_internal.c}, and @file{regex_internal.h}. @item Be willing to continue to maintain the port. @@ -28192,10 +28224,10 @@ The Robot @cindex adding, functions to @command{gawk} @c STARTOFRANGE fubadgaw @cindex functions, built-in, adding to @command{gawk} -Beginning with @command{gawk} 3.1, it is possible to add new built-in +It is possible to add new built-in functions to @command{gawk} using dynamically loaded libraries. This facility is available on systems (such as GNU/Linux) that support -the @code{dlopen} and @code{dlsym} functions. +the C @code{dlopen()} and @code{dlsym()} functions. This @value{SECTION} describes how to write and use dynamically loaded extensions for @command{gawk}. Experience with programming in @@ -28203,7 +28235,7 @@ C or C++ is necessary when reading this @value{SECTION}. @strong{Caution:} The facilities described in this @value{SECTION} are very much subject to change in a future @command{gawk} release. -Be aware that you may have to re-do everything, perhaps from scratch, +Be aware that you may have to re-do everything, at some future time. @strong{Caution:} If you have written your own dynamic extensions, @@ -28212,7 +28244,8 @@ There is no guarantee of binary compatibility between different releases, nor will there ever be such a guarantee. @quotation NOTE -When @option{--sandbox} is specified, extensions are disabled. +When @option{--sandbox} is specified, extensions are disabled +(@pxref{Options}. @end quotation @menu @@ -28257,20 +28290,27 @@ floating-point numbers. Typically, it is a C @code{double}. Just about everything is done using objects of type @code{NODE}. These contain both strings and numbers, as well as variables and arrays. -@cindex @code{force_number} internal function +@cindex @code{force_number()} internal function @cindex numeric, values @item AWKNUM force_number(NODE *n) This macro forces a value to be numeric. It returns the actual numeric value contained in the node. It may end up calling an internal @command{gawk} function. -@cindex @code{force_string} internal function +@cindex @code{force_string()} internal function @item void force_string(NODE *n) This macro guarantees that a @code{NODE}'s string value is current. It may end up calling an internal @command{gawk} function. It also guarantees that the string is zero-terminated. -@cindex @code{get_curfunc_arg_count} internal function +@cindex @code{force_wstring()} internal function +@item void force_wstring(NODE *n) +Similarly, this +macro guarantees that a @code{NODE}'s wide-string value is current. +It may end up calling an internal @command{gawk} function. +It also guarantees that the wide string is zero-terminated. + +@cindex @code{get_curfunc_arg_count()} internal function @item size_t get_curfunc_arg_count(void) This function returns the actual number of parameters passed to the current function. Inside the code of an extension @@ -28279,13 +28319,11 @@ safe to use with @code{get_actual_argument}. If this value is greater than @code{nargs}, the function was called incorrectly from the @command{awk} program. -@strong{Caution:} This function is new as of @command{gawk} 3.1.4. - @cindex parameters@comma{} number of @cindex @code{nargs} internal variable @item nargs Inside an extension function, this is the maximum number of -expected parameters, as set by the @code{make_builtin} function. +expected parameters, as set by the @code{make_builtin()} function. @cindex @code{stptr} internal variable @cindex @code{stlen} internal variable @@ -28297,11 +28335,18 @@ If you need to pass the string value to a C library function, save the value in @code{n->stptr[n->stlen]}, assign @code{'\0'} to it, call the routine, and then restore the value. +@cindex @code{wstptr} internal variable +@cindex @code{wstlen} internal variable +@item n->wstptr +@itemx n->wstlen +The data and length of a @code{NODE}'s wide-string value, respectively. +Use @code{force_wstring()} to make sure these values are current. + @cindex @code{type} internal variable @item n->type The type of the @code{NODE}. This is a C @code{enum}. Values should -be either @code{Node_var} or @code{Node_var_array} for function -parameters. +be one of @code{Node_var}, @code{Node_var_new}, or @code{Node_var_array} +for function parameters. @cindex @code{vname} internal variable @item n->vname @@ -28309,13 +28354,13 @@ The ``variable name'' of a node. This is not of much use inside externally written extensions. @cindex arrays, associative, clearing -@cindex @code{assoc_clear} internal function +@cindex @code{assoc_clear()} internal function @item void assoc_clear(NODE *n) Clears the associative array pointed to by @code{n}. Make sure that @samp{n->type == Node_var_array} first. @cindex arrays, elements, installing -@cindex @code{assoc_lookup} internal function +@cindex @code{assoc_lookup()} internal function @item NODE **assoc_lookup(NODE *symbol, NODE *subs, int reference) Finds, and installs if necessary, array elements. @code{symbol} is the array, @code{subs} is the subscript. @@ -28325,14 +28370,14 @@ value before it is created. Typically, @code{FALSE} is the correct value to use from extension functions. @cindex strings -@cindex @code{make_string} internal function +@cindex @code{make_string()} internal function @item NODE *make_string(char *s, size_t len) Take a C string and turn it into a pointer to a @code{NODE} that can be stored appropriately. This is permanent storage; understanding of @command{gawk} memory management is helpful. @cindex numbers -@cindex @code{make_number} internal function +@cindex @code{make_number()} internal function @item NODE *make_number(AWKNUM val) Take an @code{AWKNUM} and turn it into a pointer to a @code{NODE} that can be stored appropriately. This is permanent storage; understanding @@ -28340,21 +28385,21 @@ of @command{gawk} memory management is helpful. @cindex nodes@comma{} duplicating -@cindex @code{dupnode} internal function +@cindex @code{dupnode()} internal function @item NODE *dupnode(NODE *n) Duplicate a node. In most cases, this increments an internal reference count instead of actually duplicating the entire @code{NODE}; understanding of @command{gawk} memory management is helpful. @cindex memory, releasing -@cindex @code{unref} internal function +@cindex @code{unref()} internal function @item void unref(NODE *n) This macro releases the memory associated with a @code{NODE} allocated with @code{make_string} or @code{make_number}. Understanding of @command{gawk} memory management is helpful. -@cindex @code{make_builtin} internal function -@item void make_builtin(char *name, NODE *(*func)(NODE *), int count) +@cindex @code{make_builtin()} internal function +@item void make_builtin(const char *name, NODE *(*func)(NODE *), int count) Register a C function pointed to by @code{func} as new built-in function @code{name}. @code{name} is a regular C string. @code{count} is the maximum number of arguments that the function takes. @@ -28371,13 +28416,13 @@ do_xxx(int nargs) @end example @cindex arguments, retrieving -@cindex @code{get_argument} internal function +@cindex @code{get_argument()} internal function @item NODE *get_argument(int i) This function is called from within a C extension function to get the @code{i}-th argument from the function call. The first argument is argument zero. -@cindex @code{get_actual_argument} internal function +@cindex @code{get_actual_argument()} internal function @item NODE *get_actual_argument(int i, @itemx @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ int@ optional,@ int@ wantarray); This function retrieves a particular argument @code{i}. @code{wantarray} is @code{TRUE} @@ -28386,24 +28431,18 @@ if the argument should be an array, @code{FALSE} otherwise. If @code{optional} i value is @code{NULL}. It is a fatal error if @code{optional} is @code{TRUE} but the argument was not provided. -@strong{Caution:} This function is new as of @command{gawk} 3.1.4. - -@cindex @code{get_scalar_argument} internal macro +@cindex @code{get_scalar_argument()} internal macro @item get_scalar_argument(i, opt) -This is a convenience macro that calls @code{get_actual_argument}. - -@strong{Caution:} This macro is new as of @command{gawk} 3.1.4. +This is a convenience macro that calls @code{get_actual_argument()}. -@cindex @code{get_array_argument} internal macro +@cindex @code{get_array_argument()} internal macro @item get_array_argument(i, opt) -This is a convenience macro that calls @code{get_actual_argument}. - -@strong{Caution:} This macro is new as of @command{gawk} 3.1.4. +This is a convenience macro that calls @code{get_actual_argument()}. @cindex functions, return values@comma{} setting @cindex @code{ERRNO} variable -@cindex @code{update_ERRNO} internal function +@cindex @code{update_ERRNO()} internal function @item void update_ERRNO(void) This function is called from within a C extension function to set the value of @command{gawk}'s @code{ERRNO} variable, based on the current @@ -28411,55 +28450,51 @@ value of the C @code{errno} variable. It is provided as a convenience. @cindex @code{ERRNO} variable -@cindex @code{update_ERRNO_saved} internal function +@cindex @code{update_ERRNO_saved()} internal function @item void update_ERRNO_saved(int errno_saved) This function is called from within a C extension function to set the value of @command{gawk}'s @code{ERRNO} variable, based on the saved value of the C @code{errno} variable provided as the argument. It is provided as a convenience. -@strong{Caution:} This function is new as of @command{gawk} 3.1.5. - @cindex @code{ENVIRON} variable @cindex @code{PROCINFO} variable -@cindex @code{register_deferred_variable} internal function +@cindex @code{register_deferred_variable()} internal function @item void register_deferred_variable(const char *name, NODE *(*load_func)(void)) This function is called to register a function to be called when a reference to an undefined variable with the given name is encountered. The callback function will never be called if the variable exists already, so, unless the calling code is running at program startup, it should first check whether a variable of the given name already exists. -The argument function must return a pointer to a NODE containing the +The argument function must return a pointer to a @code{NODE} containing the newly created variable. This function is used to implement the builtin @code{ENVIRON} and @code{PROCINFO} variables, so you can refer to them for examples. -@strong{Caution:} This function is new as of @command{gawk} 3.1.5. - @cindex @code{IOBUF} internal structure -@cindex @code{iop_alloc} internal function -@cindex @code{get_record} input method -@cindex @code{close_func} input method +@cindex @code{iop_alloc()} internal function +@cindex @code{get_record()} input method +@cindex @code{close_func}() input method @cindex XML -@cindex @code{register_open_hook} internal function +@cindex @code{register_open_hook()} internal function @item void register_open_hook(void *(*open_func)(IOBUF *)) This function is called to register a function to be called whenever a new data file is opened, leading to the creation of an @code{IOBUF} -structure in @code{iop_alloc}. After creating the new @code{IOBUF}, -@code{iop_alloc} will call (in reverse order of registration, so the last +structure in @code{iop_alloc()}. After creating the new @code{IOBUF}, +@code{iop_alloc()} will call (in reverse order of registration, so the last function registered is called first) each open hook until one returns -non-NULL. If any hook returns a non-NULL value, that value is assigned +non-@code{NULL}. If any hook returns a non-@code{NULL} value, that value is assigned to the @code{IOBUF}'s @code{opaque} field (which will presumably point to a structure containing additional state associated with the input processing), and no further open hooks are called. The function called will most likely want to set the @code{IOBUF} -@code{get_record} method to indicate that future input records should +@code{get_record()} method to indicate that future input records should be retrieved by calling that method instead of using the standard @command{gawk} input processing. And the function will also probably want to set the @code{IOBUF} -@code{close_func} method to be called when the file is closed to clean +@code{close_func()} method to be called when the file is closed to clean up any state associated with the input. Finally, hook functions should be prepared to receive an @code{IOBUF} @@ -28471,65 +28506,13 @@ and place a valid file descriptor there. Currently, for example, the hook function facility is used to implement the XML parser shared library extension. For more info, please look in @file{awk.h} and in @file{io.c}. - -@strong{Caution:} This function is new as of @command{gawk} 3.1.5. @end table An argument that is supposed to be an array needs to be handled with some extra code, in case the array being passed in is actually from a function parameter. -In versions of @command{gawk} up to and including 3.1.2, the -following boilerplate code shows how to do this: - -@smallexample -NODE *the_arg; - -the_arg = get_argument(tree, 2); /* assume need 3rd arg, 0-based */ - -/* if a parameter, get it off the stack */ -if (the_arg->type == Node_param_list) - the_arg = stack_ptr[the_arg->param_cnt]; - -/* parameter referenced an array, get it */ -if (the_arg->type == Node_array_ref) - the_arg = the_arg->orig_array; - -/* check type */ -if (the_arg->type != Node_var && the_arg->type != Node_var_array) - fatal("newfunc: third argument is not an array"); - -/* force it to be an array, if necessary, clear it */ -the_arg->type = Node_var_array; -assoc_clear(the_arg); -@end smallexample - -For versions 3.1.3 and later, the internals changed. In particular, -the interface was actually @emph{simplified} drastically. The -following boilerplate code now suffices: - -@smallexample -NODE *the_arg; - -the_arg = get_argument(tree, 2); /* assume need 3rd arg, 0-based */ - -/* force it to be an array: */ -the_arg = get_array(the_arg); - -/* if necessary, clear it: */ -assoc_clear(the_arg); -@end smallexample - -In @value{PVERSION} 3.1.4, the internals improved again, and became -even simpler: - -@smallexample -NODE *the_arg; - -the_arg = get_array_argument(tree, 2, FALSE); /* assume need 3rd arg, 0-based */ -@end smallexample - -As of @value{PVERSION} 4.0, the internals changed again: +The following boilerplate code shows how to do this: @smallexample NODE *the_arg; @@ -28558,19 +28541,19 @@ int plugin_is_GPL_compatible; @end example @node Sample Library -@appendixsubsec Directory and File Operation Built-ins +@appendixsubsec Example: Directory and File Operation Built-ins @c STARTOFRANGE chdirg -@cindex @code{chdir} function@comma{} implementing in @command{gawk} +@cindex @code{chdir()} function@comma{} implementing in @command{gawk} @c STARTOFRANGE statg -@cindex @code{stat} function@comma{} implementing in @command{gawk} +@cindex @code{stat()} function@comma{} implementing in @command{gawk} @c STARTOFRANGE filre @cindex files, information about@comma{} retrieving @c STARTOFRANGE dirch @cindex directories, changing -Two useful functions that are not in @command{awk} are @code{chdir} +Two useful functions that are not in @command{awk} are @code{chdir()} (so that an @command{awk} program can change its directory) and -@code{stat} (so that an @command{awk} program can gather information about +@code{stat()} (so that an @command{awk} program can gather information about a file). This @value{SECTION} implements these functions for @command{gawk} in an external extension library. @@ -28587,7 +28570,7 @@ external extension library. This @value{SECTION} shows how to use the new functions at the @command{awk} level once they've been integrated into the running @command{gawk} interpreter. -Using @code{chdir} is very straightforward. It takes one argument, +Using @code{chdir()} is very straightforward. It takes one argument, the new directory to change to: @example @@ -28607,8 +28590,8 @@ and @code{ERRNO} (@pxref{Built-in Variables}) is set to a string indicating the error. -Using @code{stat} is a bit more complicated. -The C @code{stat} function fills in a structure that has a fair +Using @code{stat()} is a bit more complicated. +The C @code{stat()} function fills in a structure that has a fair amount of information. The right way to model this in @command{awk} is to fill in an associative array with the appropriate information: @@ -28626,12 +28609,12 @@ if (ret < 0) @{ printf("size of %s is %d bytes\n", file, fdata["size"]) @end example -The @code{stat} function always clears the data array, even if -the @code{stat} fails. It fills in the following elements: +The @code{stat()} function always clears the data array, even if +the @code{stat()} fails. It fills in the following elements: @table @code @item "name" -The name of the file that was @code{stat}'ed. +The name of the file that was @code{stat()}'ed. @item "dev" @itemx "ino" @@ -28724,7 +28707,7 @@ of that number, respectively. @end table @node Internal File Ops -@appendixsubsubsec C Code for @code{chdir} and @code{stat} +@appendixsubsubsec C Code for @code{chdir()} and @code{stat()} Here is the C code for these extensions. They were written for GNU/Linux. The code needs some more work for complete portability @@ -29089,32 +29072,6 @@ Integrating Fred Fish's DBUG library would be helpful during development, but it's a lot of work to do. @end table -Following is a list of probable improvements that will make @command{gawk} -perform better: - -@table @asis -@strong{FIXME: NEXT ED:} remove this item. awka and mawk do these respectively. -@item Compilation of @command{awk} programs -@command{gawk} uses a Bison (YACC-like) -parser to convert the script given it into a syntax tree; the syntax -tree is then executed by a simple recursive evaluator. This method incurs -a lot of overhead, since the recursive evaluator performs many procedure -calls to do even the simplest things. - -It should be possible for @command{gawk} to convert the script's parse tree -into a C program which the user would then compile, using the normal -C compiler and a special @command{gawk} library to provide all the needed -functions (regexps, fields, associative arrays, type coercion, and so on). - -@cindex @command{gawk}, interpreter@comma{} adding code to -An easier possibility might be for an intermediate phase of @command{gawk} to -convert the parse tree into a linear byte code form like the one used -in GNU Emacs Lisp. The recursive evaluator would then be replaced by -a straight line byte code interpreter that would be intermediate in speed -between running a compiled program and doing what @command{gawk} does -now. -@end table - Finally, the programs in the test suite could use documenting in this @value{DOCUMENT}. |