diff options
Diffstat (limited to 'doc/awkcard.in')
| -rw-r--r-- | doc/awkcard.in | 147 |
1 files changed, 83 insertions, 64 deletions
diff --git a/doc/awkcard.in b/doc/awkcard.in index a0abfa74..9df71344 100644 --- a/doc/awkcard.in +++ b/doc/awkcard.in @@ -26,7 +26,6 @@ .\" Strings to save typing .ds AK \*(FCawk\*(FR .ds GK \*(FCgawk\*(FR -.ds PK \*(FCpgawk\*(FR .ds NK Bell Labs \*(FCawk\*(FR .ds MK \*(FCmawk\*(FR .\" @@ -77,7 +76,7 @@ Pattern Elements 8 Printf Formats 14 Records 10 Regular Expressions 11 -Signals (\*(PK) 4 +Signals (\*(GK \*(FC\-\^\-profile\*(FR) 4 Special Filenames 12 String Functions 16 Time Functions (\*(GK) 17 @@ -254,6 +253,9 @@ their types and final values to If no \*(FIfile\*(FR is provided, \*(FCgawk\*(FR uses \*(FCawkvars.out\*(FR. +.TI "\*(FC\-D\*(FR[\*(FC\*(FIfile\*(FR], \*(FC\-\^\-debug\*(FR[\*(FC=\*(FIfile\*(FR] +Enable debugging of program. Optionally read stored commands +from \*(FIfile\*(FR. .TI "\*(FC-e '\*(FItext\*(FC'\*(FR, \*(FC\-\^\-source '\*(FItext\*(FC'\*(FR Use \*(FItext\*(FR as AWK program source code. .TI "\*(FC\-E \*(FIfile\*(FR, \*(FC\-\^\-exec \*(FIfile\*(FR @@ -269,6 +271,10 @@ for localization. .TI "\*(FC\-h\*(FR, \*(FC\-\^\-help\*(FR Print a short summary of the available options on \*(FCstdout\*(FR, then exit zero. +.TI "\*(FC\-i \*(FIfile\*(FR, \*(FC\-\^\-include \*(FIfile\*(FR +Include library AWK code in \*(FIfile\*(FR. +.TI "\*(FC\-l \*(FIlib\*(FR, \*(FC\-\^\-load \*(FIlib\*(FR +Load dynamic extension \*(FIlib\fP. .TI "\*(FC\-L \*(FR[\*(FC\*(FIvalue\*(FR], \*(FC\-\^\-lint\*(FR[\*(FC=\*(FIvalue\*(FR] Warn about dubious or non-portable constructs. If \*(FIvalue\*(FR is @@ -278,36 +284,25 @@ If \*(FIvalue\*(FR is \*(FCinvalid\*(FR, only issue warnings about things that are actually invalid (not fully implemented yet). +.TI "\*(FC\-M\*(FR, \*(FC\-\^\-bignum\*(FR +Enable arbitrary-precision arithmetic. .TI "\*(FC\-n\*(FR, \*(FC\-\^\-non\-decimal\-data\*(FR Recognize octal and hexadecimal values in input data. \*(FIUse this option with great caution!\*(FR .TI "\*(FC\-N\*(FR, \*(FC\-\^\-use\-lc\-numeric\*(FR Force use of the locale's decimal point character when parsing input data. +.TI "\*(FC\-o\*(FR[\*(FC\*(FIfile\*(FR], \*(FC\-\^\-pretty-print\*(FR[\*(FC=\*(FIfile\*(FR] +Output a pretty printed version of the program to \*(FIfile\*(FR +(default: \*(FCawkprof.out\*(FR). .TI "\*(FC\-O\*(FR, \*(FC\-\^\-optimize\*(FR Enable some internal optimizations. .TI "\*(FC\-p\*(FR[\*(FC\*(FIfile\*(FR], \*(FC\-\^\-profile\*(FR[\*(FC=\*(FIfile\*(FR] Send profiling data to \*(FIfile\*(FR (default: \*(FCawkprof.out\*(FR). -With \*(GK, -the profile is just a ``pretty printed'' version of the program. -With \*(PK, -the profile contains execution counts in the left margin +The profile contains execution counts in the left margin of each statement in the program. .TI "\*(FC\-P\*(FR, \*(FC\-\^\-posix\*(FR -Disable common and GNU extensions. -.TI "\*(FC\-R \*(FIfile\*(FR, \*(FC\-\^\-command \*(FIfile\*(FR" -\*(FCdgawk\*(FR only. -Read stored debugger commands from \*(FIfile\*(FR. -.TI "\*(FC\-r\*(FR, \*(FC\-\^\-re\-interval\*(FR -Enable \*(FIinterval expressions\*(FR in regular -expression matching (see \fHRegular -Expressions\fP below). Useful if -\*(FC\-\^\-traditional\*(FR is specified. -.TI "\*(FC\-S\*(FR, \*(FC\-\^\-sandbox\*(FR -Disable the \*(FCsystem()\*(FR function, -input redirection with \*(FCgetline\*(FR, -output redirection with \*(FCprint\*(FR and \*(FCprintf\*(FR, -and dynamic extensions loading.\*(CB +Disable common and GNU extensions.\*(CB .in -4n .EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0" @@ -319,6 +314,13 @@ and dynamic extensions loading.\*(CB .ES .fi .in +4n +.TI "\*(FC\-r\*(FR, \*(FC\-\^\-re\-interval\*(FR +Enable \*(FIinterval expressions\*(FR. +.TI "\*(FC\-S\*(FR, \*(FC\-\^\-sandbox\*(FR +Disable the \*(FCsystem()\*(FR function, +input redirection with \*(FCgetline\*(FR, +output redirection with \*(FCprint\*(FR and \*(FCprintf\*(FR, +and dynamic extensions loading. .TI "\*(FC-t\*(FR, \*(FC\-\^\-lint\-old\*(FR Warn about constructs that are not portable to the original version of @@ -338,7 +340,7 @@ options are passed on to the AWK program in \*(FCARGV\*(FR for processing.\*(CB .EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(GK\f(HB)\*(FR\s0" - +.sp .4 .\" .\" .\" --- Command Line Arguments (mawk) @@ -383,14 +385,14 @@ The options may be abbreviated using just the first letter, e.g., and so on.\*(CB .EB "\s+2\f(HBCOMMAND LINE ARGUMENTS (\*(MK\f(HB)\*(FR\s0" .sp .7 -.\" --- Signals (pgawk) +.\" --- Signals (gawk --profile) .ES .fi -\*(CD\*(PK accepts two signals. +\*(CD\*(GK accepts two signals while profiling. \*(FCSIGUSR1\fP dumps a profile and function call stack to the profile file. It then continues to run. \*(FCSIGHUP\fP is similar, but exits.\*(CB -.EB "\s+2\f(HBSIGNALS (\*(PK\f(HB)\*(FR\s0" +.EB "\s+2\f(HBSIGNALS (\*(GK \f(HB\-\^\-profile)\*(FR\s0" .\" --- Lines And Statements .ES @@ -450,7 +452,7 @@ The program text is read as if all the \*(FIprog-file\*(FR(s) \*(CBand command line source texts\*(CD had been concatenated. .sp -\*(GK includes files named on \*(FC@include\*(FR lines. +\*(CB\*(GK includes files named on \*(FC@include\*(FR lines. Nested includes are allowed.\*(CD .sp .5 AWK programs execute in the following order. @@ -545,7 +547,7 @@ variables, each element being the value of that variable. T} \*(CB\*(FCERRNO\fP T{ -String describing the error if a +String error value if a \*(FCgetline\*(FR redirection or read fails, or if @@ -574,6 +576,10 @@ T} Input field separator, a space by default (see \fHFields\fP above). T} +\*(CB\*(FCFUNCTAB\fP T{ +An array indexed by the names of all user-defined +and extension functions.\*(CD +T} \*(CB\*(FCIGNORECASE\fP T{ If non-zero, all regular expression and string operations ignore case. @@ -588,13 +594,8 @@ T} \*(CB\*(FCLINT\fP T{ Provides dynamic control of the \*(FC\-\^\-lint\fP option from within an AWK program. -When true, \*(GK -prints lint warnings. -When assigned the string value \*(FC"fatal"\*(FR, -lint warnings become fatal errors. -Any other true value just prints warnings.\*(CD T} -\*(FCNF\fP T{ +\*(CD\*(FCNF\fP T{ Number of fields in the current input record. T} \*(FCNR\fP T{ @@ -609,7 +610,11 @@ T} \*(FCORS\fP T{ Output record separator, a newline by default. T} -\*(CB\*(FCPROCINFO\fP T{ +\*(CB\*(FCPREC\fP T{ +The working precision of arbitrary precision floating-point +numbers, 53 by default. +T} +\*(FCPROCINFO\fP T{ Elements of this array provide access to information about the running AWK program. See \*(AM for details.\*(CD @@ -618,6 +623,10 @@ T} Length of the string matched by \*(FCmatch()\*(FR; \-1 if no match. T} +\*(CB\*(FCROUNDMODE\fP T{ +The rounding mode to use for arbitrary precision arithmetic, +by default \*(FC"N"\fP.\*(CD +T} \*(FCRS\fP T{ Input record separator, a newline by default (see \fHRecords\fP above). @@ -636,6 +645,11 @@ Character(s) used to separate multiple subscripts in array elements, by default \*(FC"\e034"\*(FR. (See \fHArrays\fP below). T} +\*(CB\*(FCSYMTAB\fP T{ +An array indexed by the names of all global +variables and arrays. May be used to indirectly +set variable and array values.\*(CD +T} \*(CB\*(FCTEXTDOMAIN\fP T{ The internationalization text domain, for finding the localized @@ -1129,7 +1143,10 @@ The default path is If a file name given to the \*(FC\-f\fP option contains a ``/'' character, no path search is performed. .sp .5 -.PP +The variable \*(FCAWKLIBPATH\fP +specifies the search path for dynamic extensions to use +with \*(FC@load\fP and the \*(FC\-l\fP option. +.sp .5 For socket communication, \*(FCGAWK_SOCK_RETRIES\fP controls the number of retries, and @@ -1139,6 +1156,10 @@ The interval is in milliseconds. On systems that do not support \*(FIusleep\fP(3), the value is rounded up to an integral number of seconds. .sp .5 +The value of \*(FCGAWK_READ_TIMEOUT\fP specifies the time, in milliseconds, +for \*(GK to +wait for input before returning with an error. +.sp .5 If \*(FCPOSIXLY_CORRECT\fP exists .\" in the environment, then \*(GK @@ -1267,11 +1288,16 @@ T} \*(FCgetline \*(FIv \*(FC< \*(FIfile\*(FR Set \*(FIv\fP from next record of \*(FIfile\*(FR. \*(FIcmd \*(FC| getline\*(FR Pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR. \*(FIcmd \*(FC| getline \*(FIv\*(FR Pipe into \*(FCgetline\*(FR; set \*(FIv\*(FR. -\*(CB\*(FIcmd \*(FC|& getline\*(FR Co-process pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR. +.\" \*(CB\*(FIcmd \*(FC|& getline\*(FR Co-process pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR. .TE .fi .in +.2i .ti -.2i +\*(CB\*(FIcmd \*(FC|& getline\*(FR +.br +Co-process pipe into \*(FCgetline\*(FR; set \*(FC$0\*(FR, \*(FCNF\*(FR. +.br +.ti -.2i \*(FIcmd \*(FC|& getline \*(FIv\*(FR .br Co-process pipe into \*(FCgetline\*(FR; set \*(FIv\*(FR. @@ -1289,10 +1315,10 @@ execute any \*(FCEND\fP rule(s). .br Stop processing the current input file. The next input record comes from the -next input file. \*(FCFILENAME\fP \*(CBand -\*(FCARGIND\fP\*(CD are updated, \*(FCFNR\fP is reset to 1, -and processing starts over with the first -pattern in the AWK program. Upon end +next input file. Update \*(FCFILENAME\fP \*(CBand +\*(FCARGIND\fP\*(CD, reset \*(FCFNR\fP to 1, +and start over with the first +pattern. Upon end of input data, execute any \*(FCEND\fP rule(s). .in -.2i .sp .5 @@ -1301,7 +1327,7 @@ of input data, execute any \*(FCEND\fP rule(s). \*(CBUpon an error, \*(FCERRNO\*(FR contains a string describing the problem.\*(CX .EB "\s+2\f(HBINPUT CONTROL\*(FR\s0" - +.sp .6 .\" --- Output Control .ES .fi @@ -1358,7 +1384,7 @@ Print data down a pipeline to \*(FIcmd\*(FR. Print data down a pipeline to co-process \*(FIcmd\*(FR.\*(CX .in -.2i .EB "\s+2\f(HBOUTPUT CONTROL\*(FR\s0" - +.sp .6 .\" --- Closing Redirections .ES .fi @@ -1474,8 +1500,8 @@ T} Precision. The meaning of the \*(FIprec\*(FR varies by control letter: T} - \*(FC%d\*(FR, \*(FC%o\*(FR, \*(FC%i\*(FR, - \*(FC%u\*(FR, \*(FC%x\*(FR, \*(FC%X\fP T{ + \*(FC%d\*(FR,\|\*(FC%o\*(FR,\|\*(FC%i\fP, \0 + \*(FC%u\*(FR,\|\*(FC%x\*(FR,\|\*(FC%X\fP T{ The minimum number of digits to print. T} \*(FC%e\*(FR, \*(FC%E\*(FR, \*(FC%f\*(FR T{ @@ -1581,7 +1607,7 @@ l lw(2i). \*(FCexp(\*(FIexpr\*(FC)\*(FR The exponential function (\*(FIe \*(FC^ \*(FIx\*(FR). \*(FCint(\*(FIexpr\*(FC)\*(FR Truncate to integer. \*(FClog(\*(FIexpr\*(FC)\*(FR The natural logarithm function (base \*(FIe\^\*(FR). -\*(FCrand()\fP A random number between 0 and 1 (0 \(<= \*(FIN\fP < 1). +\*(FCrand()\fP A random number \*(FIN\fP such that 0 \(<= \*(FIN\fP < 1. \*(FCsin(\*(FIexpr\*(FC)\*(FR The sine of \*(FIexpr\fP, which is in radians. \*(FCsqrt(\*(FIexpr\*(FC)\*(FR The square root function. \&\*(FCsrand(\*(FR[\*(FIexpr\^\*(FR]\*(FC)\*(FR T{ @@ -1798,10 +1824,9 @@ provides the following functions for doing bitwise operations. .fi .in +.2i .ti -.2i -\*(FCand(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR +\*(FCand(\*(FIv1\*(FC, \*(FIv2\*(FR [\*(FC,\*(FR ... ]\*(FC)\*(FR .br -Return the bitwise AND of the values provided by -\*(FIv1\*(FR and \*(FIv2\*(FR. +Return the bitwise AND of the arguments. .ti -.2i \*(FCcompl(\*(FIval\*(FC)\*(FR .br @@ -1813,20 +1838,18 @@ Return the bitwise complement of Return the value of \*(FIval\*(FR, shifted left by \*(FIcount\*(FR bits. .ti -.2i -\*(FCor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR +\*(FCor(\*(FIv1\*(FC, \*(FIv2\*(FR [\*(FC,\*(FR ... ]\*(FC)\*(FR .br -Return the bitwise OR of the values provided by -\*(FIv1\*(FR and \*(FIv2\*(FR. +Return the bitwise OR of the arguments. .ti -.2i \*(FCrshift(\*(FIval\*(FC, \*(FIcount\*(FC)\*(FR .br Return the value of \*(FIval\*(FR, shifted right by \*(FIcount\*(FR bits. .ti -.2i -\*(FCxor(\*(FIv1\*(FC, \*(FIv2\*(FC)\*(FR +\*(FCxor(\*(FIv1\*(FC, \*(FIv2\*(FR [\*(FC,\*(FR ... ]\*(FC)\*(FR .br -Return the bitwise XOR of the values provided by -\*(FIv1\*(FR and \*(FIv2\*(FR.\*(CB +Return the bitwise XOR of the arguments.\*(CB .in -.2i .EB "\s+2\f(HBBIT MANIPULATION FUNCTIONS (\*(GK\f(HB)\*(FR\s0" .sp .6 @@ -1835,16 +1858,15 @@ Return the bitwise XOR of the values provided by .fi .in +.2i .ti -.2i -\*(CD\*(FCextension(\*(FIlib\*(FC, \*(FIfunc\*(FC)\*(FR +\*(CD\*(FC@load "\*(FIextension\*(FC"\*(FR .br -Dynamically load the shared library -\*(FIlib\*(FR -and call -\*(FIfunc\*(FR -in it to initialize the library. +Dynamically load the named \*(FIextension\*(FR. This adds new built-in functions to \*(GK. -It returns the value returned by -\*(FIfunc\*(FR.\*(CB +.\" The extension should use the API defined by the +.\" \*(FCgawkapi.h\*(FR header file, as documented in +.\" the full manual. +The extension is loaded during the parsing of the program. +See the manual for details.\*(CB .in -.2i .EB "\s+2\f(HBDYNAMIC EXTENSIONS (\*(GK\f(HB)\*(FR\s0" .BT @@ -1929,9 +1951,6 @@ GCC (the GNU Compiler Collection) works well. .in -.2i .nf .sp .4 -... Host: \*(FCftp.whidbey.net\*(FR -... File: \*(FC/pub/brennan/mawk1.3.3.tar.gz\fP -... \*(FChttp://www.skeeve.com/gawk/mawk1.3.3.tar.gz\fP Host: \*(FCinvisible-island.net\*(FR File: \*(FC/mawk/mawk.tar.gz\fP .in +.2i |