diff options
Diffstat (limited to 'doc/gawk.info')
| -rw-r--r-- | doc/gawk.info | 1765 |
1 files changed, 884 insertions, 881 deletions
diff --git a/doc/gawk.info b/doc/gawk.info index 4c10ab10..797a35a6 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -89,14 +89,14 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Functions:: Built-in and user-defined functions. * Internationalization:: Getting `gawk' to speak your language. -* Arbitrary Precision Arithmetic:: Arbitrary precision arithmetic with - `gawk'. * Advanced Features:: Stuff for advanced users, specific to `gawk'. * Library Functions:: A Library of `awk' Functions. * Sample Programs:: Many `awk' programs with complete explanations. * Debugger:: The `gawk' debugger. +* Arbitrary Precision Arithmetic:: Arbitrary precision arithmetic with + `gawk'. * Dynamic Extensions:: Adding new built-in functions to `gawk'. * Language History:: The evolution of the `awk' @@ -361,29 +361,6 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * I18N Portability:: `awk'-level portability issues. * I18N Example:: A simple i18n example. * Gawk I18N:: `gawk' is also internationalized. -* General Arithmetic:: An introduction to computer arithmetic. -* Floating Point Issues:: Stuff to know about floating-point numbers. -* String Conversion Precision:: The String Value Can Lie. -* Unexpected Results:: Floating Point Numbers Are Not Abstract - Numbers. -* POSIX Floating Point Problems:: Standards Versus Existing Practice. -* Integer Programming:: Effective integer programming. -* Floating-point Programming:: Effective Floating-point Programming. -* Floating-point Representation:: Binary floating-point representation. -* Floating-point Context:: Floating-point context. -* Rounding Mode:: Floating-point rounding mode. -* Gawk and MPFR:: How `gawk' provides - aribitrary-precision arithmetic. -* Arbitrary Precision Floats:: Arbitrary Precision Floating-point - Arithmetic with `gawk'. -* Setting Precision:: Setting the working precision. -* Setting Rounding Mode:: Setting the rounding mode. -* Floating-point Constants:: Representing floating-point constants. -* Changing Precision:: Changing the precision of a number. -* Exact Arithmetic:: Exact arithmetic with floating-point - numbers. -* Arbitrary Precision Integers:: Arbitrary Precision Integer Arithmetic with - `gawk'. * Nondecimal Data:: Allowing nondecimal input data. * Array Sorting:: Facilities for controlling array traversal and sorting arrays. @@ -465,6 +442,29 @@ texts being (a) (see below), and with the Back-Cover Texts being (b) * Miscellaneous Debugger Commands:: Miscellaneous Commands. * Readline Support:: Readline support. * Limitations:: Limitations and future plans. +* General Arithmetic:: An introduction to computer arithmetic. +* Floating Point Issues:: Stuff to know about floating-point numbers. +* String Conversion Precision:: The String Value Can Lie. +* Unexpected Results:: Floating Point Numbers Are Not Abstract + Numbers. +* POSIX Floating Point Problems:: Standards Versus Existing Practice. +* Integer Programming:: Effective integer programming. +* Floating-point Programming:: Effective Floating-point Programming. +* Floating-point Representation:: Binary floating-point representation. +* Floating-point Context:: Floating-point context. +* Rounding Mode:: Floating-point rounding mode. +* Gawk and MPFR:: How `gawk' provides + aribitrary-precision arithmetic. +* Arbitrary Precision Floats:: Arbitrary Precision Floating-point + Arithmetic with `gawk'. +* Setting Precision:: Setting the working precision. +* Setting Rounding Mode:: Setting the rounding mode. +* Floating-point Constants:: Representing floating-point constants. +* Changing Precision:: Changing the precision of a number. +* Exact Arithmetic:: Exact arithmetic with floating-point + numbers. +* Arbitrary Precision Integers:: Arbitrary Precision Integer Arithmetic with + `gawk'. * Plugin License:: A note about licensing. * Sample Library:: A example of new functions. * Internal File Description:: What the new functions will do. @@ -878,6 +878,9 @@ real problems. *note Arbitrary Precision Arithmetic::, describes advanced arithmetic facilities provided by `gawk'. + *note Dynamic Extensions::, describes how to add new variables and +functions to `gawk' by writing extensions in C. + *note Language History::, describes how the `awk' language has evolved since its first release to present. It also describes how `gawk' has acquired features over time. @@ -13180,7 +13183,7 @@ example, in the following case: `gawk' will look up the actual function to call only once. -File: gawk.info, Node: Internationalization, Next: Arbitrary Precision Arithmetic, Prev: Functions, Up: Top +File: gawk.info, Node: Internationalization, Next: Advanced Features, Prev: Functions, Up: Top 10 Internationalization with `gawk' *********************************** @@ -13760,7 +13763,7 @@ writing, the latest version of GNU `gettext' is version 0.18.1 usage messages, warnings, and fatal errors in the local language. -File: gawk.info, Node: Advanced Features, Next: Library Functions, Prev: Arbitrary Precision Arithmetic, Up: Top +File: gawk.info, Node: Advanced Features, Next: Library Functions, Prev: Internationalization, Up: Top 11 Advanced Features of `gawk' ****************************** @@ -18982,7 +18985,7 @@ supplies the following copyright terms: We leave it to you to determine what the program does. -File: gawk.info, Node: Debugger, Next: Dynamic Extensions, Prev: Sample Programs, Up: Top +File: gawk.info, Node: Debugger, Next: Arbitrary Precision Arithmetic, Prev: Sample Programs, Up: Top 14 Debugging `awk' Programs *************************** @@ -20034,402 +20037,9 @@ features may be added, and of course feel free to try to add them yourself! -File: gawk.info, Node: Dynamic Extensions, Next: Language History, Prev: Debugger, Up: Top - -15 Writing Extensions for `gawk' -******************************** - -This chapter is a placeholder, pending a rewrite for the new API. Some -of the old bits remain, since they can be partially reused. - - It is possible to add new built-in functions to `gawk' using -dynamically loaded libraries. This facility is available on systems -(such as GNU/Linux) that support the C `dlopen()' and `dlsym()' -functions. This major node describes how to write and use dynamically -loaded extensions for `gawk'. Experience with programming in C or C++ -is necessary when reading this minor node. - - NOTE: When `--sandbox' is specified, extensions are disabled - (*note Options::. - -* Menu: - -* Plugin License:: A note about licensing. -* Sample Library:: A example of new functions. - - -File: gawk.info, Node: Plugin License, Next: Sample Library, Up: Dynamic Extensions - -15.1 Extension Licensing -======================== - -Every dynamic extension should define the global symbol -`plugin_is_GPL_compatible' to assert that it has been licensed under a -GPL-compatible license. If this symbol does not exist, `gawk' will -emit a fatal error and exit. - - The declared type of the symbol should be `int'. It does not need -to be in any allocated section, though. The code merely asserts that -the symbol exists in the global scope. Something like this is enough: - - int plugin_is_GPL_compatible; - - -File: gawk.info, Node: Sample Library, Prev: Plugin License, Up: Dynamic Extensions - -15.2 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' -program can gather information about a file). This minor node -implements these functions for `gawk' in an external extension library. - -* Menu: - -* Internal File Description:: What the new functions will do. -* Internal File Ops:: The code for internal file operations. -* Using Internal File Ops:: How to use an external extension. - - -File: gawk.info, Node: Internal File Description, Next: Internal File Ops, Up: Sample Library - -15.2.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 -directory to change to: - - ... - newdir = "/home/arnold/funstuff" - ret = chdir(newdir) - if (ret < 0) { - printf("could not change to %s: %s\n", - newdir, ERRNO) > "/dev/stderr" - exit 1 - } - ... - - 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 -appropriate information: - - file = "/home/arnold/.profile" - fdata[1] = "x" # force `fdata' to be an array - ret = stat(file, fdata) - if (ret < 0) { - printf("could not stat %s: %s\n", - file, ERRNO) > "/dev/stderr" - exit 1 - } - 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: - -`"name"' - The name of the file that was `stat()''ed. - -`"dev"' -`"ino"' - The file's device and inode numbers, respectively. - -`"mode"' - The file's mode, as a numeric value. This includes both the file's - type and its permissions. - -`"nlink"' - The number of hard links (directory entries) the file has. - -`"uid"' -`"gid"' - The numeric user and group ID numbers of the file's owner. - -`"size"' - The size in bytes of the file. - -`"blocks"' - The number of disk blocks the file actually occupies. This may not - be a function of the file's size if the file has holes. - -`"atime"' -`"mtime"' -`"ctime"' - The file's last access, modification, and inode update times, - respectively. These are numeric timestamps, suitable for - formatting with `strftime()' (*note Built-in::). - -`"pmode"' - The file's "printable mode." This is a string representation of - the file's type and permissions, such as what is produced by `ls - -l'--for example, `"drwxr-xr-x"'. - -`"type"' - A printable string representation of the file's type. The value - is one of the following: - - `"blockdev"' - `"chardev"' - The file is a block or character device ("special file"). - - `"directory"' - The file is a directory. - - `"fifo"' - The file is a named-pipe (also known as a FIFO). - - `"file"' - The file is just a regular file. - - `"socket"' - The file is an `AF_UNIX' ("Unix domain") socket in the - filesystem. - - `"symlink"' - The file is a symbolic link. - - Several additional elements may be present depending upon the -operating system and the type of the file. You can test for them in -your `awk' program by using the `in' operator (*note Reference to -Elements::): - -`"blksize"' - The preferred block size for I/O to the file. This field is not - present on all POSIX-like systems in the C `stat' structure. - -`"linkval"' - If the file is a symbolic link, this element is the name of the - file the link points to (i.e., the value of the link). - -`"rdev"' -`"major"' -`"minor"' - If the file is a block or character device file, then these values - represent the numeric device number and the major and minor - components of that number, respectively. - - -File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops, Prev: Internal File Description, Up: Sample Library - -15.2.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 -other POSIX-compliant systems:(1) - - #include "awk.h" - - #include <sys/sysmacros.h> - - int plugin_is_GPL_compatible; - - /* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ - - static NODE * - do_chdir(int nargs) - { - NODE *newdir; - int ret = -1; - - if (do_lint && nargs != 1) - lintwarn("chdir: called with incorrect number of arguments"); - - newdir = get_scalar_argument(0, FALSE); - - The file includes the `"awk.h"' header file for definitions for the -`gawk' internals. It includes `<sys/sysmacros.h>' for access to the -`major()' and `minor'() macros. - - By convention, for an `awk' function `foo', the function that -implements it is called `do_foo'. The function should take a `int' -argument, usually called `nargs', that represents the number of defined -arguments for the function. The `newdir' variable represents the new -directory to change to, retrieved with `get_scalar_argument()'. Note -that the first argument is numbered zero. - - This code actually accomplishes the `chdir()'. It first forces the -argument to be a string and passes the string value to the `chdir()' -system call. If the `chdir()' fails, `ERRNO' is updated. - - (void) force_string(newdir); - ret = chdir(newdir->stptr); - if (ret < 0) - update_ERRNO_int(errno); - - Finally, the function returns the return value to the `awk' level: - - return make_number((AWKNUM) ret); - } - - The `stat()' built-in is more involved. First comes a function that -turns a numeric mode into a printable representation (e.g., 644 becomes -`-rw-r--r--'). This is omitted here for brevity: - - /* format_mode --- turn a stat mode field into something readable */ - - static char * - format_mode(unsigned long fmode) - { - ... - } - - Next comes the `do_stat()' function. It starts with variable -declarations and argument checking: - - /* do_stat --- provide a stat() function for gawk */ - - static NODE * - do_stat(int nargs) - { - NODE *file, *array, *tmp; - struct stat sbuf; - int ret; - NODE **aptr; - char *pmode; /* printable mode */ - char *type = "unknown"; - - if (do_lint && nargs > 2) - lintwarn("stat: called with too many arguments"); - - Then comes the actual work. First, the function gets the arguments. -Then, it always clears the array. The code use `lstat()' (instead of -`stat()') to get the file information, in case the file is a symbolic -link. If there's an error, it sets `ERRNO' and returns: - - /* file is first arg, array to hold results is second */ - file = get_scalar_argument(0, FALSE); - array = get_array_argument(1, FALSE); - - /* empty out the array */ - assoc_clear(array); - - /* lstat the file, if error, set ERRNO and return */ - (void) force_string(file); - ret = lstat(file->stptr, & sbuf); - if (ret < 0) { - update_ERRNO_int(errno); - return make_number((AWKNUM) ret); - } - - Now comes the tedious part: filling in the array. Only a few of the -calls are shown here, since they all follow the same pattern: - - /* fill in the array */ - aptr = assoc_lookup(array, tmp = make_string("name", 4)); - *aptr = dupnode(file); - unref(tmp); - - aptr = assoc_lookup(array, tmp = make_string("mode", 4)); - *aptr = make_number((AWKNUM) sbuf.st_mode); - unref(tmp); - - aptr = assoc_lookup(array, tmp = make_string("pmode", 5)); - pmode = format_mode(sbuf.st_mode); - *aptr = make_string(pmode, strlen(pmode)); - unref(tmp); - - When done, return the `lstat()' return value: - - - return make_number((AWKNUM) ret); - } - - Finally, it's necessary to provide the "glue" that loads the new -function(s) into `gawk'. By convention, each library has a routine -named `dl_load()' that does the job. The simplest way is to use the -`dl_load_func' macro in `gawkapi.h'. - - And that's it! As an exercise, consider adding functions to -implement system calls such as `chown()', `chmod()', and `umask()'. - - ---------- Footnotes ---------- - - (1) This version is edited slightly for presentation. See -`extension/filefuncs.c' in the `gawk' distribution for the complete -version. - - -File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops, Up: Sample Library - -15.2.3 Integrating the Extensions ---------------------------------- - -Now that the code is written, it must be possible to add it at runtime -to the running `gawk' interpreter. First, the code must be compiled. -Assuming that the functions are in a file named `filefuncs.c', and IDIR -is the location of the `gawk' include files, the following steps create -a GNU/Linux shared library: +File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Dynamic Extensions, Prev: Debugger, Up: Top - $ gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -IIDIR filefuncs.c - $ ld -o filefuncs.so -shared filefuncs.o - - Once the library exists, it is loaded by calling the `extension()' -built-in function. This function takes two arguments: the name of the -library to load and the name of a function to call when the library is -first loaded. This function adds the new functions to `gawk'. It -returns the value returned by the initialization function within the -shared library: - - # file testff.awk - BEGIN { - extension("./filefuncs.so", "dl_load") - - chdir(".") # no-op - - data[1] = 1 # force `data' to be an array - print "Info for testff.awk" - ret = stat("testff.awk", data) - print "ret =", ret - for (i in data) - printf "data[\"%s\"] = %s\n", i, data[i] - print "testff.awk modified:", - strftime("%m %d %y %H:%M:%S", data["mtime"]) - - print "\nInfo for JUNK" - ret = stat("JUNK", data) - print "ret =", ret - for (i in data) - printf "data[\"%s\"] = %s\n", i, data[i] - print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) - } - - Here are the results of running the program: - - $ gawk -f testff.awk - -| Info for testff.awk - -| ret = 0 - -| data["size"] = 607 - -| data["ino"] = 14945891 - -| data["name"] = testff.awk - -| data["pmode"] = -rw-rw-r-- - -| data["nlink"] = 1 - -| data["atime"] = 1293993369 - -| data["mtime"] = 1288520752 - -| data["mode"] = 33204 - -| data["blksize"] = 4096 - -| data["dev"] = 2054 - -| data["type"] = file - -| data["gid"] = 500 - -| data["uid"] = 500 - -| data["blocks"] = 8 - -| data["ctime"] = 1290113572 - -| testff.awk modified: 10 31 10 12:25:52 - -| - -| Info for JUNK - -| ret = -1 - -| JUNK modified: 01 01 70 02:00:00 - - -File: gawk.info, Node: Arbitrary Precision Arithmetic, Next: Advanced Features, Prev: Internationalization, Up: Top - -16 Arithmetic and Arbitrary Precision Arithmetic with `gawk' +15 Arithmetic and Arbitrary Precision Arithmetic with `gawk' ************************************************************ There's a credibility gap: We don't know how much of the @@ -20470,7 +20080,7 @@ feature which is specific to `gawk'. File: gawk.info, Node: General Arithmetic, Next: Floating-point Programming, Up: Arbitrary Precision Arithmetic -16.1 A General Description of Computer Arithmetic +15.1 A General Description of Computer Arithmetic ================================================= Within computers, there are two kinds of numeric values: "integers" and @@ -20506,7 +20116,7 @@ precision" floating-point numbers. File: gawk.info, Node: Floating Point Issues, Next: Integer Programming, Up: General Arithmetic -16.1.1 Floating-Point Number Caveats +15.1.1 Floating-Point Number Caveats ------------------------------------ As mentioned earlier, floating-point numbers represent what are called @@ -20532,7 +20142,7 @@ in computer science. File: gawk.info, Node: String Conversion Precision, Next: Unexpected Results, Up: Floating Point Issues -16.1.1.1 The String Value Can Lie +15.1.1.1 The String Value Can Lie ................................. Internally, `awk' keeps both the numeric value (double precision @@ -20584,7 +20194,7 @@ doubt that you need to worry about this. File: gawk.info, Node: Unexpected Results, Next: POSIX Floating Point Problems, Prev: String Conversion Precision, Up: Floating Point Issues -16.1.1.2 Floating Point Numbers Are Not Abstract Numbers +15.1.1.2 Floating Point Numbers Are Not Abstract Numbers ........................................................ Unlike numbers in the abstract sense (such as what you studied in high @@ -20638,7 +20248,7 @@ noted and can affect comparisons. File: gawk.info, Node: POSIX Floating Point Problems, Prev: Unexpected Results, Up: Floating Point Issues -16.1.1.3 Standards Versus Existing Practice +15.1.1.3 Standards Versus Existing Practice ........................................... Historically, `awk' has converted any non-numeric looking string to the @@ -20726,7 +20336,7 @@ as follows: File: gawk.info, Node: Integer Programming, Prev: Floating Point Issues, Up: General Arithmetic -16.1.2 Mixing Integers And Floating-point +15.1.2 Mixing Integers And Floating-point ----------------------------------------- As has been mentioned already, `gawk' ordinarily uses hardware double @@ -20762,7 +20372,7 @@ around on your screen. File: gawk.info, Node: Floating-point Programming, Next: Gawk and MPFR, Prev: General Arithmetic, Up: Arbitrary Precision Arithmetic -16.2 Understanding Floating-point Programming +15.2 Understanding Floating-point Programming ============================================= Numerical programming is an extensive area; if you need to develop @@ -20922,7 +20532,7 @@ more information. File: gawk.info, Node: Floating-point Representation, Next: Floating-point Context, Up: Floating-point Programming -16.2.1 Binary Floating-point Representation +15.2.1 Binary Floating-point Representation ------------------------------------------- Although floating-point representations vary from machine to machine, @@ -20951,7 +20561,7 @@ the first bit is always a one. File: gawk.info, Node: Floating-point Context, Next: Rounding Mode, Prev: Floating-point Representation, Up: Floating-point Programming -16.2.2 Floating-point Context +15.2.2 Floating-point Context ----------------------------- A floating-point "context" defines the environment for arithmetic @@ -20983,7 +20593,7 @@ Single 32 24 -126 +127 Double 64 53 -1022 +1023 Quadruple 128 113 -16382 +16383 -Table 16.1: Basic IEEE Format Context Values +Table 15.1: Basic IEEE Format Context Values NOTE: The precision numbers include the implied leading one that gives them one extra bit of significand. @@ -21007,7 +20617,7 @@ corresponding to 64-bit binary with 53 bits of precision. File: gawk.info, Node: Rounding Mode, Prev: Floating-point Context, Up: Floating-point Programming -16.2.3 Floating-point Rounding Mode +15.2.3 Floating-point Rounding Mode ----------------------------------- The "rounding mode" specifies the behavior for the results of numerical @@ -21025,7 +20635,7 @@ Round toward zero `roundTowardZero' Round to nearest, ties away `roundTiesToAway' from zero -Table 16.2: IEEE 754 Rounding Modes +Table 15.2: IEEE 754 Rounding Modes The default mode `roundTiesToEven' is the most preferred, but the least intuitive. This method does the obvious thing for most values, by @@ -21094,7 +20704,7 @@ to round halfway cases for `printf()'. File: gawk.info, Node: Gawk and MPFR, Next: Arbitrary Precision Floats, Prev: Floating-point Programming, Up: Arbitrary Precision Arithmetic -16.3 `gawk' + MPFR = Powerful Arithmetic +15.3 `gawk' + MPFR = Powerful Arithmetic ======================================== The rest of this major node decsribes how to use the arbitrary precision @@ -21124,7 +20734,7 @@ Auto-set::, for more information. File: gawk.info, Node: Arbitrary Precision Floats, Next: Arbitrary Precision Integers, Prev: Gawk and MPFR, Up: Arbitrary Precision Arithmetic -16.4 Arbitrary Precision Floating-point Arithmetic with `gawk' +15.4 Arbitrary Precision Floating-point Arithmetic with `gawk' ============================================================== `gawk' uses the GNU MPFR library for arbitrary precision floating-point @@ -21177,7 +20787,7 @@ and subnormal numbers are not implemented. File: gawk.info, Node: Setting Precision, Next: Setting Rounding Mode, Up: Arbitrary Precision Floats -16.4.1 Setting the Working Precision +15.4.1 Setting the Working Precision ------------------------------------ `gawk' uses a global working precision; it does not keep track of the @@ -21239,7 +20849,7 @@ issues that occur because numbers are stored internally in binary. File: gawk.info, Node: Setting Rounding Mode, Next: Floating-point Constants, Prev: Setting Precision, Up: Arbitrary Precision Floats -16.4.2 Setting the Rounding Mode +15.4.2 Setting the Rounding Mode -------------------------------- The `ROUNDMODE' variable provides program level control over the @@ -21255,11 +20865,11 @@ Round toward zero `roundTowardZero' `"Z"' or `"z"' Round to nearest, ties away `roundTiesToAway' `"A"' or `"a"' from zero -Table 16.3: `gawk' Rounding Modes +Table 15.3: `gawk' Rounding Modes `ROUNDMODE' has the default value `"N"', which selects the IEEE-754 rounding mode `roundTiesToEven'. Besides the values listed in *note -Table 16.3: table-gawk-rounding-modes, `gawk' also accepts `"A"' to +Table 15.3: table-gawk-rounding-modes, `gawk' also accepts `"A"' to select the IEEE-754 mode `roundTiesToAway' if your version of the MPFR library supports it; otherwise setting `ROUNDMODE' to this value has no effect. *Note Rounding Mode::, for the meanings of the various rounding @@ -21274,7 +20884,7 @@ modes. File: gawk.info, Node: Floating-point Constants, Next: Changing Precision, Prev: Setting Rounding Mode, Up: Arbitrary Precision Floats -16.4.3 Representing Floating-point Constants +15.4.3 Representing Floating-point Constants -------------------------------------------- Be wary of floating-point constants! When reading a floating-point @@ -21304,7 +20914,7 @@ of 53. File: gawk.info, Node: Changing Precision, Next: Exact Arithmetic, Prev: Floating-point Constants, Up: Arbitrary Precision Floats -16.4.4 Changing the Precision of a Number +15.4.4 Changing the Precision of a Number ----------------------------------------- The point is that in any variable-precision package, a decision is @@ -21343,7 +20953,7 @@ Volume 28, pp. 168-173, 2008. File: gawk.info, Node: Exact Arithmetic, Prev: Changing Precision, Up: Arbitrary Precision Floats -16.4.5 Exact Arithmetic with Floating-point Numbers +15.4.5 Exact Arithmetic with Floating-point Numbers --------------------------------------------------- CAUTION: Never depend on the exactness of floating-point @@ -21414,7 +21024,7 @@ hand is often the correct approach in such situations. File: gawk.info, Node: Arbitrary Precision Integers, Prev: Arbitrary Precision Floats, Up: Arbitrary Precision Arithmetic -16.5 Arbitrary Precision Integer Arithmetic with `gawk' +15.5 Arbitrary Precision Integer Arithmetic with `gawk' ======================================================= If the option `--bignum' or `-M' is specified, `gawk' performs all @@ -21489,6 +21099,399 @@ Wolfram Web Resource. `http://mathworld.wolfram.com/SylvestersSequence.html' +File: gawk.info, Node: Dynamic Extensions, Next: Language History, Prev: Arbitrary Precision Arithmetic, Up: Top + +16 Writing Extensions for `gawk' +******************************** + +This chapter is a placeholder, pending a rewrite for the new API. Some +of the old bits remain, since they can be partially reused. + + It is possible to add new built-in functions to `gawk' using +dynamically loaded libraries. This facility is available on systems +(such as GNU/Linux) that support the C `dlopen()' and `dlsym()' +functions. This major node describes how to write and use dynamically +loaded extensions for `gawk'. Experience with programming in C or C++ +is necessary when reading this minor node. + + NOTE: When `--sandbox' is specified, extensions are disabled + (*note Options::. + +* Menu: + +* Plugin License:: A note about licensing. +* Sample Library:: A example of new functions. + + +File: gawk.info, Node: Plugin License, Next: Sample Library, Up: Dynamic Extensions + +16.1 Extension Licensing +======================== + +Every dynamic extension should define the global symbol +`plugin_is_GPL_compatible' to assert that it has been licensed under a +GPL-compatible license. If this symbol does not exist, `gawk' will +emit a fatal error and exit. + + The declared type of the symbol should be `int'. It does not need +to be in any allocated section, though. The code merely asserts that +the symbol exists in the global scope. Something like this is enough: + + int plugin_is_GPL_compatible; + + +File: gawk.info, Node: Sample Library, Prev: Plugin License, Up: Dynamic Extensions + +16.2 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' +program can gather information about a file). This minor node +implements these functions for `gawk' in an external extension library. + +* Menu: + +* Internal File Description:: What the new functions will do. +* Internal File Ops:: The code for internal file operations. +* Using Internal File Ops:: How to use an external extension. + + +File: gawk.info, Node: Internal File Description, Next: Internal File Ops, Up: Sample Library + +16.2.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 +directory to change to: + + ... + newdir = "/home/arnold/funstuff" + ret = chdir(newdir) + if (ret < 0) { + printf("could not change to %s: %s\n", + newdir, ERRNO) > "/dev/stderr" + exit 1 + } + ... + + 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 +appropriate information: + + file = "/home/arnold/.profile" + fdata[1] = "x" # force `fdata' to be an array + ret = stat(file, fdata) + if (ret < 0) { + printf("could not stat %s: %s\n", + file, ERRNO) > "/dev/stderr" + exit 1 + } + 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: + +`"name"' + The name of the file that was `stat()''ed. + +`"dev"' +`"ino"' + The file's device and inode numbers, respectively. + +`"mode"' + The file's mode, as a numeric value. This includes both the file's + type and its permissions. + +`"nlink"' + The number of hard links (directory entries) the file has. + +`"uid"' +`"gid"' + The numeric user and group ID numbers of the file's owner. + +`"size"' + The size in bytes of the file. + +`"blocks"' + The number of disk blocks the file actually occupies. This may not + be a function of the file's size if the file has holes. + +`"atime"' +`"mtime"' +`"ctime"' + The file's last access, modification, and inode update times, + respectively. These are numeric timestamps, suitable for + formatting with `strftime()' (*note Built-in::). + +`"pmode"' + The file's "printable mode." This is a string representation of + the file's type and permissions, such as what is produced by `ls + -l'--for example, `"drwxr-xr-x"'. + +`"type"' + A printable string representation of the file's type. The value + is one of the following: + + `"blockdev"' + `"chardev"' + The file is a block or character device ("special file"). + + `"directory"' + The file is a directory. + + `"fifo"' + The file is a named-pipe (also known as a FIFO). + + `"file"' + The file is just a regular file. + + `"socket"' + The file is an `AF_UNIX' ("Unix domain") socket in the + filesystem. + + `"symlink"' + The file is a symbolic link. + + Several additional elements may be present depending upon the +operating system and the type of the file. You can test for them in +your `awk' program by using the `in' operator (*note Reference to +Elements::): + +`"blksize"' + The preferred block size for I/O to the file. This field is not + present on all POSIX-like systems in the C `stat' structure. + +`"linkval"' + If the file is a symbolic link, this element is the name of the + file the link points to (i.e., the value of the link). + +`"rdev"' +`"major"' +`"minor"' + If the file is a block or character device file, then these values + represent the numeric device number and the major and minor + components of that number, respectively. + + +File: gawk.info, Node: Internal File Ops, Next: Using Internal File Ops, Prev: Internal File Description, Up: Sample Library + +16.2.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 +other POSIX-compliant systems:(1) + + #include "awk.h" + + #include <sys/sysmacros.h> + + int plugin_is_GPL_compatible; + + /* do_chdir --- provide dynamically loaded chdir() builtin for gawk */ + + static NODE * + do_chdir(int nargs) + { + NODE *newdir; + int ret = -1; + + if (do_lint && nargs != 1) + lintwarn("chdir: called with incorrect number of arguments"); + + newdir = get_scalar_argument(0, FALSE); + + The file includes the `"awk.h"' header file for definitions for the +`gawk' internals. It includes `<sys/sysmacros.h>' for access to the +`major()' and `minor'() macros. + + By convention, for an `awk' function `foo', the function that +implements it is called `do_foo'. The function should take a `int' +argument, usually called `nargs', that represents the number of defined +arguments for the function. The `newdir' variable represents the new +directory to change to, retrieved with `get_scalar_argument()'. Note +that the first argument is numbered zero. + + This code actually accomplishes the `chdir()'. It first forces the +argument to be a string and passes the string value to the `chdir()' +system call. If the `chdir()' fails, `ERRNO' is updated. + + (void) force_string(newdir); + ret = chdir(newdir->stptr); + if (ret < 0) + update_ERRNO_int(errno); + + Finally, the function returns the return value to the `awk' level: + + return make_number((AWKNUM) ret); + } + + The `stat()' built-in is more involved. First comes a function that +turns a numeric mode into a printable representation (e.g., 644 becomes +`-rw-r--r--'). This is omitted here for brevity: + + /* format_mode --- turn a stat mode field into something readable */ + + static char * + format_mode(unsigned long fmode) + { + ... + } + + Next comes the `do_stat()' function. It starts with variable +declarations and argument checking: + + /* do_stat --- provide a stat() function for gawk */ + + static NODE * + do_stat(int nargs) + { + NODE *file, *array, *tmp; + struct stat sbuf; + int ret; + NODE **aptr; + char *pmode; /* printable mode */ + char *type = "unknown"; + + if (do_lint && nargs > 2) + lintwarn("stat: called with too many arguments"); + + Then comes the actual work. First, the function gets the arguments. +Then, it always clears the array. The code use `lstat()' (instead of +`stat()') to get the file information, in case the file is a symbolic +link. If there's an error, it sets `ERRNO' and returns: + + /* file is first arg, array to hold results is second */ + file = get_scalar_argument(0, FALSE); + array = get_array_argument(1, FALSE); + + /* empty out the array */ + assoc_clear(array); + + /* lstat the file, if error, set ERRNO and return */ + (void) force_string(file); + ret = lstat(file->stptr, & sbuf); + if (ret < 0) { + update_ERRNO_int(errno); + return make_number((AWKNUM) ret); + } + + Now comes the tedious part: filling in the array. Only a few of the +calls are shown here, since they all follow the same pattern: + + /* fill in the array */ + aptr = assoc_lookup(array, tmp = make_string("name", 4)); + *aptr = dupnode(file); + unref(tmp); + + aptr = assoc_lookup(array, tmp = make_string("mode", 4)); + *aptr = make_number((AWKNUM) sbuf.st_mode); + unref(tmp); + + aptr = assoc_lookup(array, tmp = make_string("pmode", 5)); + pmode = format_mode(sbuf.st_mode); + *aptr = make_string(pmode, strlen(pmode)); + unref(tmp); + + When done, return the `lstat()' return value: + + + return make_number((AWKNUM) ret); + } + + Finally, it's necessary to provide the "glue" that loads the new +function(s) into `gawk'. By convention, each library has a routine +named `dl_load()' that does the job. The simplest way is to use the +`dl_load_func' macro in `gawkapi.h'. + + And that's it! As an exercise, consider adding functions to +implement system calls such as `chown()', `chmod()', and `umask()'. + + ---------- Footnotes ---------- + + (1) This version is edited slightly for presentation. See +`extension/filefuncs.c' in the `gawk' distribution for the complete +version. + + +File: gawk.info, Node: Using Internal File Ops, Prev: Internal File Ops, Up: Sample Library + +16.2.3 Integrating the Extensions +--------------------------------- + +Now that the code is written, it must be possible to add it at runtime +to the running `gawk' interpreter. First, the code must be compiled. +Assuming that the functions are in a file named `filefuncs.c', and IDIR +is the location of the `gawk' include files, the following steps create +a GNU/Linux shared library: + + $ gcc -fPIC -shared -DHAVE_CONFIG_H -c -O -g -IIDIR filefuncs.c + $ ld -o filefuncs.so -shared filefuncs.o + + Once the library exists, it is loaded by calling the `extension()' +built-in function. This function takes two arguments: the name of the +library to load and the name of a function to call when the library is +first loaded. This function adds the new functions to `gawk'. It +returns the value returned by the initialization function within the +shared library: + + # file testff.awk + BEGIN { + extension("./filefuncs.so", "dl_load") + + chdir(".") # no-op + + data[1] = 1 # force `data' to be an array + print "Info for testff.awk" + ret = stat("testff.awk", data) + print "ret =", ret + for (i in data) + printf "data[\"%s\"] = %s\n", i, data[i] + print "testff.awk modified:", + strftime("%m %d %y %H:%M:%S", data["mtime"]) + + print "\nInfo for JUNK" + ret = stat("JUNK", data) + print "ret =", ret + for (i in data) + printf "data[\"%s\"] = %s\n", i, data[i] + print "JUNK modified:", strftime("%m %d %y %H:%M:%S", data["mtime"]) + } + + Here are the results of running the program: + + $ gawk -f testff.awk + -| Info for testff.awk + -| ret = 0 + -| data["size"] = 607 + -| data["ino"] = 14945891 + -| data["name"] = testff.awk + -| data["pmode"] = -rw-rw-r-- + -| data["nlink"] = 1 + -| data["atime"] = 1293993369 + -| data["mtime"] = 1288520752 + -| data["mode"] = 33204 + -| data["blksize"] = 4096 + -| data["dev"] = 2054 + -| data["type"] = file + -| data["gid"] = 500 + -| data["uid"] = 500 + -| data["blocks"] = 8 + -| data["ctime"] = 1290113572 + -| testff.awk modified: 10 31 10 12:25:52 + -| + -| Info for JUNK + -| ret = -1 + -| JUNK modified: 01 01 70 02:00:00 + + File: gawk.info, Node: Language History, Next: Installation, Prev: Dynamic Extensions, Up: Top Appendix A The Evolution of the `awk' Language @@ -28429,441 +28432,441 @@ Node: History39607 Node: Names41998 Ref: Names-Footnote-143475 Node: This Manual43547 -Ref: This Manual-Footnote-148556 -Node: Conventions48656 -Node: Manual History50790 -Ref: Manual History-Footnote-154060 -Ref: Manual History-Footnote-254101 -Node: How To Contribute54175 -Node: Acknowledgments55319 -Node: Getting Started59815 -Node: Running gawk62194 -Node: One-shot63380 -Node: Read Terminal64605 -Ref: Read Terminal-Footnote-166255 -Ref: Read Terminal-Footnote-266531 -Node: Long66702 -Node: Executable Scripts68078 -Ref: Executable Scripts-Footnote-169947 -Ref: Executable Scripts-Footnote-270049 -Node: Comments70596 -Node: Quoting73063 -Node: DOS Quoting77686 -Node: Sample Data Files78361 -Node: Very Simple81393 -Node: Two Rules85992 -Node: More Complex88139 -Ref: More Complex-Footnote-191069 -Node: Statements/Lines91154 -Ref: Statements/Lines-Footnote-195616 -Node: Other Features95881 -Node: When96809 -Node: Invoking Gawk98956 -Node: Command Line100417 -Node: Options101200 -Ref: Options-Footnote-1116598 -Node: Other Arguments116623 -Node: Naming Standard Input119281 -Node: Environment Variables120375 -Node: AWKPATH Variable120933 -Ref: AWKPATH Variable-Footnote-1123691 -Node: AWKLIBPATH Variable123951 -Node: Other Environment Variables124548 -Node: Exit Status127043 -Node: Include Files127718 -Node: Loading Shared Libraries131287 -Node: Obsolete132512 -Node: Undocumented133209 -Node: Regexp133452 -Node: Regexp Usage134841 -Node: Escape Sequences136867 -Node: Regexp Operators142630 -Ref: Regexp Operators-Footnote-1150010 -Ref: Regexp Operators-Footnote-2150157 -Node: Bracket Expressions150255 -Ref: table-char-classes152145 -Node: GNU Regexp Operators154668 -Node: Case-sensitivity158391 -Ref: Case-sensitivity-Footnote-1161359 -Ref: Case-sensitivity-Footnote-2161594 -Node: Leftmost Longest161702 -Node: Computed Regexps162903 -Node: Reading Files166313 -Node: Records168316 -Ref: Records-Footnote-1177240 -Node: Fields177277 -Ref: Fields-Footnote-1180310 -Node: Nonconstant Fields180396 -Node: Changing Fields182598 -Node: Field Separators188579 -Node: Default Field Splitting191208 -Node: Regexp Field Splitting192325 -Node: Single Character Fields195667 -Node: Command Line Field Separator196726 -Node: Field Splitting Summary200167 -Ref: Field Splitting Summary-Footnote-1203359 -Node: Constant Size203460 -Node: Splitting By Content208044 -Ref: Splitting By Content-Footnote-1211770 -Node: Multiple Line211810 -Ref: Multiple Line-Footnote-1217657 -Node: Getline217836 -Node: Plain Getline220052 -Node: Getline/Variable222141 -Node: Getline/File223282 -Node: Getline/Variable/File224604 -Ref: Getline/Variable/File-Footnote-1226203 -Node: Getline/Pipe226290 -Node: Getline/Variable/Pipe228850 -Node: Getline/Coprocess229957 -Node: Getline/Variable/Coprocess231200 -Node: Getline Notes231914 -Node: Getline Summary234701 -Ref: table-getline-variants235109 -Node: Read Timeout235965 -Ref: Read Timeout-Footnote-1239710 -Node: Command line directories239767 -Node: Printing240397 -Node: Print242028 -Node: Print Examples243365 -Node: Output Separators246149 -Node: OFMT247909 -Node: Printf249267 -Node: Basic Printf250173 -Node: Control Letters251712 -Node: Format Modifiers255524 -Node: Printf Examples261533 -Node: Redirection264248 -Node: Special Files271232 -Node: Special FD271765 -Ref: Special FD-Footnote-1275390 -Node: Special Network275464 -Node: Special Caveats276314 -Node: Close Files And Pipes277110 -Ref: Close Files And Pipes-Footnote-1284133 -Ref: Close Files And Pipes-Footnote-2284281 -Node: Expressions284431 -Node: Values285563 -Node: Constants286239 -Node: Scalar Constants286919 -Ref: Scalar Constants-Footnote-1287778 -Node: Nondecimal-numbers287960 -Node: Regexp Constants291019 -Node: Using Constant Regexps291494 -Node: Variables294549 -Node: Using Variables295204 -Node: Assignment Options296928 -Node: Conversion298800 -Ref: table-locale-affects304176 -Ref: Conversion-Footnote-1304800 -Node: All Operators304909 -Node: Arithmetic Ops305539 -Node: Concatenation308044 -Ref: Concatenation-Footnote-1310837 -Node: Assignment Ops310957 -Ref: table-assign-ops315945 -Node: Increment Ops317353 -Node: Truth Values and Conditions320823 -Node: Truth Values321906 -Node: Typing and Comparison322955 -Node: Variable Typing323744 -Ref: Variable Typing-Footnote-1327641 -Node: Comparison Operators327763 -Ref: table-relational-ops328173 -Node: POSIX String Comparison331722 -Ref: POSIX String Comparison-Footnote-1332678 -Node: Boolean Ops332816 -Ref: Boolean Ops-Footnote-1336894 -Node: Conditional Exp336985 -Node: Function Calls338717 -Node: Precedence342311 -Node: Locales345980 -Node: Patterns and Actions347069 -Node: Pattern Overview348123 -Node: Regexp Patterns349792 -Node: Expression Patterns350335 -Node: Ranges354020 -Node: BEGIN/END356986 -Node: Using BEGIN/END357748 -Ref: Using BEGIN/END-Footnote-1360479 -Node: I/O And BEGIN/END360585 -Node: BEGINFILE/ENDFILE362867 -Node: Empty365771 -Node: Using Shell Variables366087 -Node: Action Overview368372 -Node: Statements370729 -Node: If Statement372583 -Node: While Statement374082 -Node: Do Statement376126 -Node: For Statement377282 -Node: Switch Statement380434 -Node: Break Statement382531 -Node: Continue Statement384521 -Node: Next Statement386314 -Node: Nextfile Statement388704 -Node: Exit Statement391249 -Node: Built-in Variables393665 -Node: User-modified394760 -Ref: User-modified-Footnote-1403115 -Node: Auto-set403177 -Ref: Auto-set-Footnote-1413085 -Node: ARGC and ARGV413290 -Node: Arrays417141 -Node: Array Basics418646 -Node: Array Intro419472 -Node: Reference to Elements423790 -Node: Assigning Elements426060 -Node: Array Example426551 -Node: Scanning an Array428283 -Node: Controlling Scanning430597 -Ref: Controlling Scanning-Footnote-1435530 -Node: Delete435846 -Ref: Delete-Footnote-1438281 -Node: Numeric Array Subscripts438338 -Node: Uninitialized Subscripts440521 -Node: Multi-dimensional442149 -Node: Multi-scanning445243 -Node: Arrays of Arrays446834 -Node: Functions451479 -Node: Built-in452301 -Node: Calling Built-in453379 -Node: Numeric Functions455367 -Ref: Numeric Functions-Footnote-1459199 -Ref: Numeric Functions-Footnote-2459556 -Ref: Numeric Functions-Footnote-3459604 -Node: String Functions459873 -Ref: String Functions-Footnote-1483370 -Ref: String Functions-Footnote-2483499 -Ref: String Functions-Footnote-3483747 -Node: Gory Details483834 -Ref: table-sub-escapes485513 -Ref: table-sub-posix-92486867 -Ref: table-sub-proposed488210 -Ref: table-posix-sub489560 -Ref: table-gensub-escapes491106 -Ref: Gory Details-Footnote-1492313 -Ref: Gory Details-Footnote-2492364 -Node: I/O Functions492515 -Ref: I/O Functions-Footnote-1499170 -Node: Time Functions499317 -Ref: Time Functions-Footnote-1510209 -Ref: Time Functions-Footnote-2510277 -Ref: Time Functions-Footnote-3510435 -Ref: Time Functions-Footnote-4510546 -Ref: Time Functions-Footnote-5510658 -Ref: Time Functions-Footnote-6510885 -Node: Bitwise Functions511151 -Ref: table-bitwise-ops511709 -Ref: Bitwise Functions-Footnote-1515930 -Node: Type Functions516114 -Node: I18N Functions516584 -Node: User-defined518211 -Node: Definition Syntax519015 -Ref: Definition Syntax-Footnote-1523925 -Node: Function Example523994 -Node: Function Caveats526588 -Node: Calling A Function527009 -Node: Variable Scope528124 -Node: Pass By Value/Reference530099 -Node: Return Statement533539 -Node: Dynamic Typing536520 -Node: Indirect Calls537255 -Node: Internationalization546940 -Node: I18N and L10N548379 -Node: Explaining gettext549065 -Ref: Explaining gettext-Footnote-1554131 -Ref: Explaining gettext-Footnote-2554315 -Node: Programmer i18n554480 -Node: Translator i18n558680 -Node: String Extraction559473 -Ref: String Extraction-Footnote-1560434 -Node: Printf Ordering560520 -Ref: Printf Ordering-Footnote-1563304 -Node: I18N Portability563368 -Ref: I18N Portability-Footnote-1565817 -Node: I18N Example565880 -Ref: I18N Example-Footnote-1568515 -Node: Gawk I18N568587 -Node: Advanced Features569204 -Node: Nondecimal Data570727 -Node: Array Sorting572310 -Node: Controlling Array Traversal573007 -Node: Array Sorting Functions581244 -Ref: Array Sorting Functions-Footnote-1584918 -Ref: Array Sorting Functions-Footnote-2585011 -Node: Two-way I/O585205 -Ref: Two-way I/O-Footnote-1590637 -Node: TCP/IP Networking590707 -Node: Profiling593551 -Node: Library Functions601005 -Ref: Library Functions-Footnote-1604012 -Node: Library Names604183 -Ref: Library Names-Footnote-1607654 -Ref: Library Names-Footnote-2607874 -Node: General Functions607960 -Node: Strtonum Function608913 -Node: Assert Function611843 -Node: Round Function615169 -Node: Cliff Random Function616712 -Node: Ordinal Functions617728 -Ref: Ordinal Functions-Footnote-1620798 -Ref: Ordinal Functions-Footnote-2621050 -Node: Join Function621259 -Ref: Join Function-Footnote-1623030 -Node: Getlocaltime Function623230 -Node: Data File Management626945 -Node: Filetrans Function627577 -Node: Rewind Function631716 -Node: File Checking633103 -Node: Empty Files634197 -Node: Ignoring Assigns636427 -Node: Getopt Function637980 -Ref: Getopt Function-Footnote-1649284 -Node: Passwd Functions649487 -Ref: Passwd Functions-Footnote-1658462 -Node: Group Functions658550 -Node: Walking Arrays666634 -Node: Sample Programs668203 -Node: Running Examples668868 -Node: Clones669596 -Node: Cut Program670820 -Node: Egrep Program680665 -Ref: Egrep Program-Footnote-1688438 -Node: Id Program688548 -Node: Split Program692164 -Ref: Split Program-Footnote-1695683 -Node: Tee Program695811 -Node: Uniq Program698614 -Node: Wc Program706043 -Ref: Wc Program-Footnote-1710309 -Ref: Wc Program-Footnote-2710509 -Node: Miscellaneous Programs710601 -Node: Dupword Program711789 -Node: Alarm Program713820 -Node: Translate Program718569 -Ref: Translate Program-Footnote-1722956 -Ref: Translate Program-Footnote-2723184 -Node: Labels Program723318 -Ref: Labels Program-Footnote-1726689 -Node: Word Sorting726773 -Node: History Sorting730657 -Node: Extract Program732496 -Ref: Extract Program-Footnote-1739979 -Node: Simple Sed740107 -Node: Igawk Program743169 -Ref: Igawk Program-Footnote-1758326 -Ref: Igawk Program-Footnote-2758527 -Node: Anagram Program758665 -Node: Signature Program761733 -Node: Debugger762833 -Node: Debugging763787 -Node: Debugging Concepts764220 -Node: Debugging Terms766076 -Node: Awk Debugging768673 -Node: Sample Debugging Session769565 -Node: Debugger Invocation770085 -Node: Finding The Bug771414 -Node: List of Debugger Commands777902 -Node: Breakpoint Control779236 -Node: Debugger Execution Control782900 -Node: Viewing And Changing Data786260 -Node: Execution Stack789616 -Node: Debugger Info791083 -Node: Miscellaneous Debugger Commands795064 -Node: Readline Support800509 -Node: Limitations801340 -Node: Dynamic Extensions803592 -Node: Plugin License804488 -Node: Sample Library805102 -Node: Internal File Description805786 -Node: Internal File Ops809499 -Ref: Internal File Ops-Footnote-1814062 -Node: Using Internal File Ops814202 -Node: Arbitrary Precision Arithmetic816578 -Ref: Arbitrary Precision Arithmetic-Footnote-1818230 -Node: General Arithmetic818378 -Node: Floating Point Issues820098 -Node: String Conversion Precision821193 -Ref: String Conversion Precision-Footnote-1822899 -Node: Unexpected Results823008 -Node: POSIX Floating Point Problems825161 -Ref: POSIX Floating Point Problems-Footnote-1828986 -Node: Integer Programming829024 -Node: Floating-point Programming830772 -Ref: Floating-point Programming-Footnote-1837036 -Node: Floating-point Representation837300 -Node: Floating-point Context838467 -Ref: table-ieee-formats839309 -Node: Rounding Mode840693 -Ref: table-rounding-modes841172 -Ref: Rounding Mode-Footnote-1844176 -Node: Gawk and MPFR844357 -Node: Arbitrary Precision Floats845598 -Ref: Arbitrary Precision Floats-Footnote-1848020 -Node: Setting Precision848331 -Node: Setting Rounding Mode851058 -Ref: table-gawk-rounding-modes851462 -Node: Floating-point Constants852659 -Node: Changing Precision854081 -Ref: Changing Precision-Footnote-1855481 -Node: Exact Arithmetic855655 -Node: Arbitrary Precision Integers858753 -Ref: Arbitrary Precision Integers-Footnote-1861835 -Node: Language History861982 -Node: V7/SVR3.1863504 -Node: SVR4865825 -Node: POSIX867267 -Node: BTL868275 -Node: POSIX/GNU869009 -Node: Common Extensions874544 -Node: Ranges and Locales875651 -Ref: Ranges and Locales-Footnote-1880269 -Ref: Ranges and Locales-Footnote-2880296 -Ref: Ranges and Locales-Footnote-3880556 -Node: Contributors880777 -Node: Installation885073 -Node: Gawk Distribution885967 -Node: Getting886451 -Node: Extracting887277 -Node: Distribution contents888969 -Node: Unix Installation894191 -Node: Quick Installation894808 -Node: Additional Configuration Options896770 -Node: Configuration Philosophy898247 -Node: Non-Unix Installation900589 -Node: PC Installation901047 -Node: PC Binary Installation902346 -Node: PC Compiling904194 -Node: PC Testing907138 -Node: PC Using908314 -Node: Cygwin912499 -Node: MSYS913499 -Node: VMS Installation914013 -Node: VMS Compilation914616 -Ref: VMS Compilation-Footnote-1915623 -Node: VMS Installation Details915681 -Node: VMS Running917316 -Node: VMS Old Gawk918923 -Node: Bugs919397 -Node: Other Versions923249 -Node: Notes928564 -Node: Compatibility Mode929151 -Node: Additions929934 -Node: Accessing The Source930861 -Node: Adding Code932286 -Node: New Ports938294 -Node: Derived Files942429 -Ref: Derived Files-Footnote-1947733 -Ref: Derived Files-Footnote-2947767 -Ref: Derived Files-Footnote-3948367 -Node: Future Extensions948465 -Node: Basic Concepts949952 -Node: Basic High Level950633 -Ref: Basic High Level-Footnote-1954668 -Node: Basic Data Typing954853 -Node: Glossary958208 -Node: Copying983184 -Node: GNU Free Documentation License1020741 -Node: Index1045878 +Ref: This Manual-Footnote-148675 +Node: Conventions48775 +Node: Manual History50909 +Ref: Manual History-Footnote-154179 +Ref: Manual History-Footnote-254220 +Node: How To Contribute54294 +Node: Acknowledgments55438 +Node: Getting Started59934 +Node: Running gawk62313 +Node: One-shot63499 +Node: Read Terminal64724 +Ref: Read Terminal-Footnote-166374 +Ref: Read Terminal-Footnote-266650 +Node: Long66821 +Node: Executable Scripts68197 +Ref: Executable Scripts-Footnote-170066 +Ref: Executable Scripts-Footnote-270168 +Node: Comments70715 +Node: Quoting73182 +Node: DOS Quoting77805 +Node: Sample Data Files78480 +Node: Very Simple81512 +Node: Two Rules86111 +Node: More Complex88258 +Ref: More Complex-Footnote-191188 +Node: Statements/Lines91273 +Ref: Statements/Lines-Footnote-195735 +Node: Other Features96000 +Node: When96928 +Node: Invoking Gawk99075 +Node: Command Line100536 +Node: Options101319 +Ref: Options-Footnote-1116717 +Node: Other Arguments116742 +Node: Naming Standard Input119400 +Node: Environment Variables120494 +Node: AWKPATH Variable121052 +Ref: AWKPATH Variable-Footnote-1123810 +Node: AWKLIBPATH Variable124070 +Node: Other Environment Variables124667 +Node: Exit Status127162 +Node: Include Files127837 +Node: Loading Shared Libraries131406 +Node: Obsolete132631 +Node: Undocumented133328 +Node: Regexp133571 +Node: Regexp Usage134960 +Node: Escape Sequences136986 +Node: Regexp Operators142749 +Ref: Regexp Operators-Footnote-1150129 +Ref: Regexp Operators-Footnote-2150276 +Node: Bracket Expressions150374 +Ref: table-char-classes152264 +Node: GNU Regexp Operators154787 +Node: Case-sensitivity158510 +Ref: Case-sensitivity-Footnote-1161478 +Ref: Case-sensitivity-Footnote-2161713 +Node: Leftmost Longest161821 +Node: Computed Regexps163022 +Node: Reading Files166432 +Node: Records168435 +Ref: Records-Footnote-1177359 +Node: Fields177396 +Ref: Fields-Footnote-1180429 +Node: Nonconstant Fields180515 +Node: Changing Fields182717 +Node: Field Separators188698 +Node: Default Field Splitting191327 +Node: Regexp Field Splitting192444 +Node: Single Character Fields195786 +Node: Command Line Field Separator196845 +Node: Field Splitting Summary200286 +Ref: Field Splitting Summary-Footnote-1203478 +Node: Constant Size203579 +Node: Splitting By Content208163 +Ref: Splitting By Content-Footnote-1211889 +Node: Multiple Line211929 +Ref: Multiple Line-Footnote-1217776 +Node: Getline217955 +Node: Plain Getline220171 +Node: Getline/Variable222260 +Node: Getline/File223401 +Node: Getline/Variable/File224723 +Ref: Getline/Variable/File-Footnote-1226322 +Node: Getline/Pipe226409 +Node: Getline/Variable/Pipe228969 +Node: Getline/Coprocess230076 +Node: Getline/Variable/Coprocess231319 +Node: Getline Notes232033 +Node: Getline Summary234820 +Ref: table-getline-variants235228 +Node: Read Timeout236084 +Ref: Read Timeout-Footnote-1239829 +Node: Command line directories239886 +Node: Printing240516 +Node: Print242147 +Node: Print Examples243484 +Node: Output Separators246268 +Node: OFMT248028 +Node: Printf249386 +Node: Basic Printf250292 +Node: Control Letters251831 +Node: Format Modifiers255643 +Node: Printf Examples261652 +Node: Redirection264367 +Node: Special Files271351 +Node: Special FD271884 +Ref: Special FD-Footnote-1275509 +Node: Special Network275583 +Node: Special Caveats276433 +Node: Close Files And Pipes277229 +Ref: Close Files And Pipes-Footnote-1284252 +Ref: Close Files And Pipes-Footnote-2284400 +Node: Expressions284550 +Node: Values285682 +Node: Constants286358 +Node: Scalar Constants287038 +Ref: Scalar Constants-Footnote-1287897 +Node: Nondecimal-numbers288079 +Node: Regexp Constants291138 +Node: Using Constant Regexps291613 +Node: Variables294668 +Node: Using Variables295323 +Node: Assignment Options297047 +Node: Conversion298919 +Ref: table-locale-affects304295 +Ref: Conversion-Footnote-1304919 +Node: All Operators305028 +Node: Arithmetic Ops305658 +Node: Concatenation308163 +Ref: Concatenation-Footnote-1310956 +Node: Assignment Ops311076 +Ref: table-assign-ops316064 +Node: Increment Ops317472 +Node: Truth Values and Conditions320942 +Node: Truth Values322025 +Node: Typing and Comparison323074 +Node: Variable Typing323863 +Ref: Variable Typing-Footnote-1327760 +Node: Comparison Operators327882 +Ref: table-relational-ops328292 +Node: POSIX String Comparison331841 +Ref: POSIX String Comparison-Footnote-1332797 +Node: Boolean Ops332935 +Ref: Boolean Ops-Footnote-1337013 +Node: Conditional Exp337104 +Node: Function Calls338836 +Node: Precedence342430 +Node: Locales346099 +Node: Patterns and Actions347188 +Node: Pattern Overview348242 +Node: Regexp Patterns349911 +Node: Expression Patterns350454 +Node: Ranges354139 +Node: BEGIN/END357105 +Node: Using BEGIN/END357867 +Ref: Using BEGIN/END-Footnote-1360598 +Node: I/O And BEGIN/END360704 +Node: BEGINFILE/ENDFILE362986 +Node: Empty365890 +Node: Using Shell Variables366206 +Node: Action Overview368491 +Node: Statements370848 +Node: If Statement372702 +Node: While Statement374201 +Node: Do Statement376245 +Node: For Statement377401 +Node: Switch Statement380553 +Node: Break Statement382650 +Node: Continue Statement384640 +Node: Next Statement386433 +Node: Nextfile Statement388823 +Node: Exit Statement391368 +Node: Built-in Variables393784 +Node: User-modified394879 +Ref: User-modified-Footnote-1403234 +Node: Auto-set403296 +Ref: Auto-set-Footnote-1413204 +Node: ARGC and ARGV413409 +Node: Arrays417260 +Node: Array Basics418765 +Node: Array Intro419591 +Node: Reference to Elements423909 +Node: Assigning Elements426179 +Node: Array Example426670 +Node: Scanning an Array428402 +Node: Controlling Scanning430716 +Ref: Controlling Scanning-Footnote-1435649 +Node: Delete435965 +Ref: Delete-Footnote-1438400 +Node: Numeric Array Subscripts438457 +Node: Uninitialized Subscripts440640 +Node: Multi-dimensional442268 +Node: Multi-scanning445362 +Node: Arrays of Arrays446953 +Node: Functions451598 +Node: Built-in452420 +Node: Calling Built-in453498 +Node: Numeric Functions455486 +Ref: Numeric Functions-Footnote-1459318 +Ref: Numeric Functions-Footnote-2459675 +Ref: Numeric Functions-Footnote-3459723 +Node: String Functions459992 +Ref: String Functions-Footnote-1483489 +Ref: String Functions-Footnote-2483618 +Ref: String Functions-Footnote-3483866 +Node: Gory Details483953 +Ref: table-sub-escapes485632 +Ref: table-sub-posix-92486986 +Ref: table-sub-proposed488329 +Ref: table-posix-sub489679 +Ref: table-gensub-escapes491225 +Ref: Gory Details-Footnote-1492432 +Ref: Gory Details-Footnote-2492483 +Node: I/O Functions492634 +Ref: I/O Functions-Footnote-1499289 +Node: Time Functions499436 +Ref: Time Functions-Footnote-1510328 +Ref: Time Functions-Footnote-2510396 +Ref: Time Functions-Footnote-3510554 +Ref: Time Functions-Footnote-4510665 +Ref: Time Functions-Footnote-5510777 +Ref: Time Functions-Footnote-6511004 +Node: Bitwise Functions511270 +Ref: table-bitwise-ops511828 +Ref: Bitwise Functions-Footnote-1516049 +Node: Type Functions516233 +Node: I18N Functions516703 +Node: User-defined518330 +Node: Definition Syntax519134 +Ref: Definition Syntax-Footnote-1524044 +Node: Function Example524113 +Node: Function Caveats526707 +Node: Calling A Function527128 +Node: Variable Scope528243 +Node: Pass By Value/Reference530218 +Node: Return Statement533658 +Node: Dynamic Typing536639 +Node: Indirect Calls537374 +Node: Internationalization547059 +Node: I18N and L10N548485 +Node: Explaining gettext549171 +Ref: Explaining gettext-Footnote-1554237 +Ref: Explaining gettext-Footnote-2554421 +Node: Programmer i18n554586 +Node: Translator i18n558786 +Node: String Extraction559579 +Ref: String Extraction-Footnote-1560540 +Node: Printf Ordering560626 +Ref: Printf Ordering-Footnote-1563410 +Node: I18N Portability563474 +Ref: I18N Portability-Footnote-1565923 +Node: I18N Example565986 +Ref: I18N Example-Footnote-1568621 +Node: Gawk I18N568693 +Node: Advanced Features569310 +Node: Nondecimal Data570823 +Node: Array Sorting572406 +Node: Controlling Array Traversal573103 +Node: Array Sorting Functions581340 +Ref: Array Sorting Functions-Footnote-1585014 +Ref: Array Sorting Functions-Footnote-2585107 +Node: Two-way I/O585301 +Ref: Two-way I/O-Footnote-1590733 +Node: TCP/IP Networking590803 +Node: Profiling593647 +Node: Library Functions601101 +Ref: Library Functions-Footnote-1604108 +Node: Library Names604279 +Ref: Library Names-Footnote-1607750 +Ref: Library Names-Footnote-2607970 +Node: General Functions608056 +Node: Strtonum Function609009 +Node: Assert Function611939 +Node: Round Function615265 +Node: Cliff Random Function616808 +Node: Ordinal Functions617824 +Ref: Ordinal Functions-Footnote-1620894 +Ref: Ordinal Functions-Footnote-2621146 +Node: Join Function621355 +Ref: Join Function-Footnote-1623126 +Node: Getlocaltime Function623326 +Node: Data File Management627041 +Node: Filetrans Function627673 +Node: Rewind Function631812 +Node: File Checking633199 +Node: Empty Files634293 +Node: Ignoring Assigns636523 +Node: Getopt Function638076 +Ref: Getopt Function-Footnote-1649380 +Node: Passwd Functions649583 +Ref: Passwd Functions-Footnote-1658558 +Node: Group Functions658646 +Node: Walking Arrays666730 +Node: Sample Programs668299 +Node: Running Examples668964 +Node: Clones669692 +Node: Cut Program670916 +Node: Egrep Program680761 +Ref: Egrep Program-Footnote-1688534 +Node: Id Program688644 +Node: Split Program692260 +Ref: Split Program-Footnote-1695779 +Node: Tee Program695907 +Node: Uniq Program698710 +Node: Wc Program706139 +Ref: Wc Program-Footnote-1710405 +Ref: Wc Program-Footnote-2710605 +Node: Miscellaneous Programs710697 +Node: Dupword Program711885 +Node: Alarm Program713916 +Node: Translate Program718665 +Ref: Translate Program-Footnote-1723052 +Ref: Translate Program-Footnote-2723280 +Node: Labels Program723414 +Ref: Labels Program-Footnote-1726785 +Node: Word Sorting726869 +Node: History Sorting730753 +Node: Extract Program732592 +Ref: Extract Program-Footnote-1740075 +Node: Simple Sed740203 +Node: Igawk Program743265 +Ref: Igawk Program-Footnote-1758422 +Ref: Igawk Program-Footnote-2758623 +Node: Anagram Program758761 +Node: Signature Program761829 +Node: Debugger762929 +Node: Debugging763895 +Node: Debugging Concepts764328 +Node: Debugging Terms766184 +Node: Awk Debugging768781 +Node: Sample Debugging Session769673 +Node: Debugger Invocation770193 +Node: Finding The Bug771522 +Node: List of Debugger Commands778010 +Node: Breakpoint Control779344 +Node: Debugger Execution Control783008 +Node: Viewing And Changing Data786368 +Node: Execution Stack789724 +Node: Debugger Info791191 +Node: Miscellaneous Debugger Commands795172 +Node: Readline Support800617 +Node: Limitations801448 +Node: Arbitrary Precision Arithmetic803700 +Ref: Arbitrary Precision Arithmetic-Footnote-1805341 +Node: General Arithmetic805489 +Node: Floating Point Issues807209 +Node: String Conversion Precision808304 +Ref: String Conversion Precision-Footnote-1810010 +Node: Unexpected Results810119 +Node: POSIX Floating Point Problems812272 +Ref: POSIX Floating Point Problems-Footnote-1816097 +Node: Integer Programming816135 +Node: Floating-point Programming817883 +Ref: Floating-point Programming-Footnote-1824147 +Node: Floating-point Representation824411 +Node: Floating-point Context825578 +Ref: table-ieee-formats826420 +Node: Rounding Mode827804 +Ref: table-rounding-modes828283 +Ref: Rounding Mode-Footnote-1831287 +Node: Gawk and MPFR831468 +Node: Arbitrary Precision Floats832709 +Ref: Arbitrary Precision Floats-Footnote-1835131 +Node: Setting Precision835442 +Node: Setting Rounding Mode838169 +Ref: table-gawk-rounding-modes838573 +Node: Floating-point Constants839770 +Node: Changing Precision841192 +Ref: Changing Precision-Footnote-1842592 +Node: Exact Arithmetic842766 +Node: Arbitrary Precision Integers845864 +Ref: Arbitrary Precision Integers-Footnote-1848946 +Node: Dynamic Extensions849093 +Node: Plugin License850011 +Node: Sample Library850625 +Node: Internal File Description851309 +Node: Internal File Ops855022 +Ref: Internal File Ops-Footnote-1859585 +Node: Using Internal File Ops859725 +Node: Language History862101 +Node: V7/SVR3.1863623 +Node: SVR4865944 +Node: POSIX867386 +Node: BTL868394 +Node: POSIX/GNU869128 +Node: Common Extensions874663 +Node: Ranges and Locales875770 +Ref: Ranges and Locales-Footnote-1880388 +Ref: Ranges and Locales-Footnote-2880415 +Ref: Ranges and Locales-Footnote-3880675 +Node: Contributors880896 +Node: Installation885192 +Node: Gawk Distribution886086 +Node: Getting886570 +Node: Extracting887396 +Node: Distribution contents889088 +Node: Unix Installation894310 +Node: Quick Installation894927 +Node: Additional Configuration Options896889 +Node: Configuration Philosophy898366 +Node: Non-Unix Installation900708 +Node: PC Installation901166 +Node: PC Binary Installation902465 +Node: PC Compiling904313 +Node: PC Testing907257 +Node: PC Using908433 +Node: Cygwin912618 +Node: MSYS913618 +Node: VMS Installation914132 +Node: VMS Compilation914735 +Ref: VMS Compilation-Footnote-1915742 +Node: VMS Installation Details915800 +Node: VMS Running917435 +Node: VMS Old Gawk919042 +Node: Bugs919516 +Node: Other Versions923368 +Node: Notes928683 +Node: Compatibility Mode929270 +Node: Additions930053 +Node: Accessing The Source930980 +Node: Adding Code932405 +Node: New Ports938413 +Node: Derived Files942548 +Ref: Derived Files-Footnote-1947852 +Ref: Derived Files-Footnote-2947886 +Ref: Derived Files-Footnote-3948486 +Node: Future Extensions948584 +Node: Basic Concepts950071 +Node: Basic High Level950752 +Ref: Basic High Level-Footnote-1954787 +Node: Basic Data Typing954972 +Node: Glossary958327 +Node: Copying983303 +Node: GNU Free Documentation License1020860 +Node: Index1045997 End Tag Table |