diff options
| -rw-r--r-- | doc/ChangeLog | 5 | ||||
| -rw-r--r-- | doc/gawk.info | 1135 | ||||
| -rw-r--r-- | doc/gawk.texi | 74 | ||||
| -rw-r--r-- | doc/gawktexi.in | 30 |
4 files changed, 691 insertions, 553 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 0a7f20f6..5c0143bf 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2020-10-28 Arnold D. Robbins <arnold@skeeve.com> + + * gawktexi.in (Other Arguments): Add a sidebar about quoting shell + variables on the command line. Based on a bug list discussion in 2018. + 2020-10-22 Arnold D. Robbins <arnold@skeeve.com> * texinfo.tex: Updated from GNULIB. diff --git a/doc/gawk.info b/doc/gawk.info index fd8f2038..03c3a883 100644 --- a/doc/gawk.info +++ b/doc/gawk.info @@ -2980,6 +2980,29 @@ example: the value of 'FS' is not strictly necessary. It remains for historical compatibility. + Quoting Shell Variables On The 'awk' Command Line + + Small 'awk' programs are often embedded in larger shell scripts, so +it's worthwhile to understand some shell basics. Consider the +following: + + f="" + awk '{ print("hi") }' $f + + In this case, 'awk' reads from standard input instead of trying to +open any command line files. To the unwary, this looks like 'awk' is +hanging. + + However 'awk' doesn't see an explicit empty string. When a variable +expansion is the null string, _and_ it's not quoted, the shell simply +removes it from the command line. To demonstrate: + + $ f="" + $ awk 'BEGIN { print ARGC }' $f + -| 1 + $ awk 'BEGIN { print ARGC }' "$f" + -| 2 + File: gawk.info, Node: Naming Standard Input, Next: Environment Variables, Prev: Other Arguments, Up: Invoking Gawk @@ -36793,6 +36816,8 @@ Index * NR variable <1>: Auto-set. (line 143) * NR variable, changing: Auto-set. (line 409) * null strings, in gawk arguments, quoting and: Quoting. (line 82) +* null strings, in gawk arguments, quoting and <1>: Other Arguments. + (line 73) * null strings: awk split records. (line 121) * null strings <1>: Regexp Field Splitting. (line 43) @@ -37170,6 +37195,7 @@ Index * quoting, in gawk command lines: Long. (line 26) * quoting, for small awk programs: Comments. (line 27) * quoting, in gawk command lines, tricks for: Quoting. (line 91) +* quoting, in gawk command lines <1>: Other Arguments. (line 73) * r debugger command (alias for run): Debugger Execution Control. (line 62) * Rakitzis, Byron: History Sorting. (line 25) @@ -37395,6 +37421,7 @@ Index * shell function, gawklibpath_prepend: Shell Startup Files. (line 25) * shell function, gawklibpath_append: Shell Startup Files. (line 29) * shell quoting, rules for: Quoting. (line 6) +* shell quoting, rules for <1>: Other Arguments. (line 73) * shells, scripts: One-shot. (line 22) * shells, quoting, rules for: Quoting. (line 18) * shells, sea: Undocumented. (line 9) @@ -37435,6 +37462,8 @@ Index (line 24) * sidebar, Recipe for a Programming Language: History. (line 6) * sidebar, Understanding #!: Executable Scripts. (line 27) +* sidebar, Quoting Shell Variables On The awk Command Line: Other Arguments. + (line 71) * sidebar, Backslash Before Regular Characters: Escape Sequences. (line 106) * sidebar, Escape Sequences for Metacharacters: Escape Sequences. @@ -37948,559 +37977,559 @@ Node: Options120292 Ref: Options-Footnote-1138206 Ref: Options-Footnote-2138437 Node: Other Arguments138462 -Node: Naming Standard Input141771 -Node: Environment Variables142981 -Node: AWKPATH Variable143539 -Ref: AWKPATH Variable-Footnote-1146951 -Ref: AWKPATH Variable-Footnote-2146985 -Node: AWKLIBPATH Variable147356 -Ref: AWKLIBPATH Variable-Footnote-1149053 -Node: Other Environment Variables149428 -Node: Exit Status153249 -Node: Include Files153926 -Node: Loading Shared Libraries157616 -Node: Obsolete159044 -Node: Undocumented159736 -Node: Invoking Summary160033 -Node: Regexp162874 -Node: Regexp Usage164328 -Node: Escape Sequences166365 -Node: Regexp Operators172606 -Node: Regexp Operator Details173091 -Ref: Regexp Operator Details-Footnote-1179523 -Node: Interval Expressions179670 -Ref: Interval Expressions-Footnote-1181091 -Node: Bracket Expressions181189 -Ref: table-char-classes183665 -Node: Leftmost Longest186991 -Node: Computed Regexps188294 -Node: GNU Regexp Operators191721 -Node: Case-sensitivity195458 -Ref: Case-sensitivity-Footnote-1198324 -Ref: Case-sensitivity-Footnote-2198559 -Node: Regexp Summary198667 -Node: Reading Files200133 -Node: Records202402 -Node: awk split records203477 -Node: gawk split records208752 -Ref: gawk split records-Footnote-1213485 -Node: Fields213522 -Node: Nonconstant Fields216263 -Ref: Nonconstant Fields-Footnote-1218499 -Node: Changing Fields218703 -Node: Field Separators224734 -Node: Default Field Splitting227432 -Node: Regexp Field Splitting228550 -Node: Single Character Fields231903 -Node: Command Line Field Separator232963 -Node: Full Line Fields236181 -Ref: Full Line Fields-Footnote-1237703 -Ref: Full Line Fields-Footnote-2237749 -Node: Field Splitting Summary237850 -Node: Constant Size239924 -Node: Fixed width data240656 -Node: Skipping intervening244123 -Node: Allowing trailing data244921 -Node: Fields with fixed data245958 -Node: Splitting By Content247476 -Ref: Splitting By Content-Footnote-1251259 -Node: More CSV251422 -Node: Testing field creation252732 -Node: Multiple Line254357 -Node: Getline260634 -Node: Plain Getline263103 -Node: Getline/Variable265676 -Node: Getline/File266827 -Node: Getline/Variable/File268215 -Ref: Getline/Variable/File-Footnote-1269820 -Node: Getline/Pipe269908 -Node: Getline/Variable/Pipe272612 -Node: Getline/Coprocess273747 -Node: Getline/Variable/Coprocess275014 -Node: Getline Notes275756 -Node: Getline Summary278553 -Ref: table-getline-variants278977 -Node: Read Timeout279725 -Ref: Read Timeout-Footnote-1283631 -Node: Retrying Input283689 -Node: Command-line directories284888 -Node: Input Summary285794 -Node: Input Exercises288966 -Node: Printing289400 -Node: Print291234 -Node: Print Examples292691 -Node: Output Separators295471 -Node: OFMT297488 -Node: Printf298844 -Node: Basic Printf299629 -Node: Control Letters301203 -Node: Format Modifiers306367 -Node: Printf Examples312382 -Node: Redirection314868 -Node: Special FD321709 -Ref: Special FD-Footnote-1324877 -Node: Special Files324951 -Node: Other Inherited Files325568 -Node: Special Network326569 -Node: Special Caveats327429 -Node: Close Files And Pipes328378 -Ref: table-close-pipe-return-values335285 -Ref: Close Files And Pipes-Footnote-1336098 -Ref: Close Files And Pipes-Footnote-2336246 -Node: Nonfatal336398 -Node: Output Summary338736 -Node: Output Exercises339958 -Node: Expressions340637 -Node: Values341825 -Node: Constants342503 -Node: Scalar Constants343194 -Ref: Scalar Constants-Footnote-1345704 -Node: Nondecimal-numbers345954 -Node: Regexp Constants348955 -Node: Using Constant Regexps349481 -Node: Standard Regexp Constants350103 -Node: Strong Regexp Constants353291 -Node: Variables356303 -Node: Using Variables356960 -Node: Assignment Options358870 -Node: Conversion361341 -Node: Strings And Numbers361865 -Ref: Strings And Numbers-Footnote-1364928 -Node: Locale influences conversions365037 -Ref: table-locale-affects367795 -Node: All Operators368413 -Node: Arithmetic Ops369042 -Node: Concatenation371758 -Ref: Concatenation-Footnote-1374605 -Node: Assignment Ops374712 -Ref: table-assign-ops379703 -Node: Increment Ops381016 -Node: Truth Values and Conditions384476 -Node: Truth Values385550 -Node: Typing and Comparison386598 -Node: Variable Typing387418 -Ref: Variable Typing-Footnote-1393881 -Ref: Variable Typing-Footnote-2393953 -Node: Comparison Operators394030 -Ref: table-relational-ops394449 -Node: POSIX String Comparison397944 -Ref: POSIX String Comparison-Footnote-1399639 -Ref: POSIX String Comparison-Footnote-2399778 -Node: Boolean Ops399862 -Ref: Boolean Ops-Footnote-1404344 -Node: Conditional Exp404436 -Node: Function Calls406172 -Node: Precedence410049 -Node: Locales413708 -Node: Expressions Summary415340 -Node: Patterns and Actions417913 -Node: Pattern Overview419033 -Node: Regexp Patterns420710 -Node: Expression Patterns421252 -Node: Ranges425033 -Node: BEGIN/END428141 -Node: Using BEGIN/END428902 -Ref: Using BEGIN/END-Footnote-1431656 -Node: I/O And BEGIN/END431762 -Node: BEGINFILE/ENDFILE434075 -Node: Empty437306 -Node: Using Shell Variables437623 -Node: Action Overview439897 -Node: Statements442222 -Node: If Statement444070 -Node: While Statement445565 -Node: Do Statement447593 -Node: For Statement448741 -Node: Switch Statement451912 -Node: Break Statement454353 -Node: Continue Statement456445 -Node: Next Statement458272 -Node: Nextfile Statement460655 -Node: Exit Statement463307 -Node: Built-in Variables465710 -Node: User-modified466843 -Node: Auto-set474610 -Ref: Auto-set-Footnote-1491417 -Ref: Auto-set-Footnote-2491623 -Node: ARGC and ARGV491679 -Node: Pattern Action Summary495892 -Node: Arrays498322 -Node: Array Basics499651 -Node: Array Intro500495 -Ref: figure-array-elements502470 -Ref: Array Intro-Footnote-1505174 -Node: Reference to Elements505302 -Node: Assigning Elements507766 -Node: Array Example508257 -Node: Scanning an Array510016 -Node: Controlling Scanning513038 -Ref: Controlling Scanning-Footnote-1519494 -Node: Numeric Array Subscripts519810 -Node: Uninitialized Subscripts521994 -Node: Delete523613 -Ref: Delete-Footnote-1526365 -Node: Multidimensional526422 -Node: Multiscanning529517 -Node: Arrays of Arrays531108 -Node: Arrays Summary535876 -Node: Functions537969 -Node: Built-in539007 -Node: Calling Built-in540088 -Node: Numeric Functions542084 -Ref: Numeric Functions-Footnote-1546112 -Ref: Numeric Functions-Footnote-2546760 -Ref: Numeric Functions-Footnote-3546808 -Node: String Functions547080 -Ref: String Functions-Footnote-1571221 -Ref: String Functions-Footnote-2571349 -Ref: String Functions-Footnote-3571597 -Node: Gory Details571684 -Ref: table-sub-escapes573475 -Ref: table-sub-proposed574994 -Ref: table-posix-sub576357 -Ref: table-gensub-escapes577898 -Ref: Gory Details-Footnote-1578721 -Node: I/O Functions578875 -Ref: table-system-return-values585329 -Ref: I/O Functions-Footnote-1587409 -Ref: I/O Functions-Footnote-2587557 -Node: Time Functions587677 -Ref: Time Functions-Footnote-1598348 -Ref: Time Functions-Footnote-2598416 -Ref: Time Functions-Footnote-3598574 -Ref: Time Functions-Footnote-4598685 -Ref: Time Functions-Footnote-5598797 -Ref: Time Functions-Footnote-6599024 -Node: Bitwise Functions599290 -Ref: table-bitwise-ops599884 -Ref: Bitwise Functions-Footnote-1605947 -Ref: Bitwise Functions-Footnote-2606120 -Node: Type Functions606311 -Node: I18N Functions609174 -Node: User-defined610825 -Node: Definition Syntax611637 -Ref: Definition Syntax-Footnote-1617331 -Node: Function Example617402 -Ref: Function Example-Footnote-1620324 -Node: Function Calling620346 -Node: Calling A Function620934 -Node: Variable Scope621892 -Node: Pass By Value/Reference624886 -Node: Function Caveats627530 -Ref: Function Caveats-Footnote-1629577 -Node: Return Statement629697 -Node: Dynamic Typing632676 -Node: Indirect Calls633606 -Ref: Indirect Calls-Footnote-1643858 -Node: Functions Summary643986 -Node: Library Functions646691 -Ref: Library Functions-Footnote-1650298 -Ref: Library Functions-Footnote-2650441 -Node: Library Names650612 -Ref: Library Names-Footnote-1654279 -Ref: Library Names-Footnote-2654502 -Node: General Functions654588 -Node: Strtonum Function655691 -Node: Assert Function658713 -Node: Round Function662039 -Node: Cliff Random Function663579 -Node: Ordinal Functions664595 -Ref: Ordinal Functions-Footnote-1667658 -Ref: Ordinal Functions-Footnote-2667910 -Node: Join Function668120 -Ref: Join Function-Footnote-1669890 -Node: Getlocaltime Function670090 -Node: Readfile Function673832 -Node: Shell Quoting675809 -Node: Data File Management677210 -Node: Filetrans Function677842 -Node: Rewind Function681938 -Node: File Checking683847 -Ref: File Checking-Footnote-1685181 -Node: Empty Files685382 -Node: Ignoring Assigns687361 -Node: Getopt Function688911 -Ref: Getopt Function-Footnote-1704122 -Node: Passwd Functions704322 -Ref: Passwd Functions-Footnote-1713161 -Node: Group Functions713249 -Ref: Group Functions-Footnote-1721147 -Node: Walking Arrays721354 -Node: Library Functions Summary724362 -Node: Library Exercises725768 -Node: Sample Programs726233 -Node: Running Examples727003 -Node: Clones727731 -Node: Cut Program728955 -Node: Egrep Program738884 -Node: Id Program747895 -Node: Split Program757842 -Ref: Split Program-Footnote-1767616 -Node: Tee Program767789 -Node: Uniq Program770579 -Node: Wc Program778143 -Node: Bytes vs. Characters778540 -Node: Using extensions780088 -Node: wc program780846 -Node: Miscellaneous Programs785711 -Node: Dupword Program786924 -Node: Alarm Program788954 -Node: Translate Program793809 -Ref: Translate Program-Footnote-1798374 -Node: Labels Program798644 -Ref: Labels Program-Footnote-1801995 -Node: Word Sorting802079 -Node: History Sorting806151 -Node: Extract Program808376 -Node: Simple Sed816430 -Node: Igawk Program819504 -Ref: Igawk Program-Footnote-1833835 -Ref: Igawk Program-Footnote-2834037 -Ref: Igawk Program-Footnote-3834159 -Node: Anagram Program834274 -Node: Signature Program837336 -Node: Programs Summary838583 -Node: Programs Exercises839797 -Ref: Programs Exercises-Footnote-1843927 -Node: Advanced Features844013 -Node: Nondecimal Data846003 -Node: Array Sorting847594 -Node: Controlling Array Traversal848294 -Ref: Controlling Array Traversal-Footnote-1856662 -Node: Array Sorting Functions856780 -Ref: Array Sorting Functions-Footnote-1861871 -Node: Two-way I/O862067 -Ref: Two-way I/O-Footnote-1869788 -Ref: Two-way I/O-Footnote-2869975 -Node: TCP/IP Networking870057 -Node: Profiling873175 -Node: Advanced Features Summary882489 -Node: Internationalization884333 -Node: I18N and L10N885813 -Node: Explaining gettext886500 -Ref: Explaining gettext-Footnote-1892392 -Ref: Explaining gettext-Footnote-2892577 -Node: Programmer i18n892742 -Ref: Programmer i18n-Footnote-1897691 -Node: Translator i18n897740 -Node: String Extraction898534 -Ref: String Extraction-Footnote-1899666 -Node: Printf Ordering899752 -Ref: Printf Ordering-Footnote-1902538 -Node: I18N Portability902602 -Ref: I18N Portability-Footnote-1905058 -Node: I18N Example905121 -Ref: I18N Example-Footnote-1908396 -Ref: I18N Example-Footnote-2908469 -Node: Gawk I18N908578 -Node: I18N Summary909227 -Node: Debugger910568 -Node: Debugging911568 -Node: Debugging Concepts912009 -Node: Debugging Terms913818 -Node: Awk Debugging916393 -Ref: Awk Debugging-Footnote-1917338 -Node: Sample Debugging Session917470 -Node: Debugger Invocation918004 -Node: Finding The Bug919390 -Node: List of Debugger Commands925864 -Node: Breakpoint Control927197 -Node: Debugger Execution Control930891 -Node: Viewing And Changing Data934253 -Node: Execution Stack937794 -Node: Debugger Info939431 -Node: Miscellaneous Debugger Commands943502 -Node: Readline Support948564 -Node: Limitations949460 -Node: Debugging Summary952014 -Node: Namespaces953293 -Node: Global Namespace954404 -Node: Qualified Names955802 -Node: Default Namespace956801 -Node: Changing The Namespace957542 -Node: Naming Rules959156 -Node: Internal Name Management961004 -Node: Namespace Example962046 -Node: Namespace And Features964608 -Node: Namespace Summary966043 -Node: Arbitrary Precision Arithmetic967520 -Node: Computer Arithmetic969007 -Ref: table-numeric-ranges972773 -Ref: table-floating-point-ranges973266 -Ref: Computer Arithmetic-Footnote-1973924 -Node: Math Definitions973981 -Ref: table-ieee-formats977297 -Ref: Math Definitions-Footnote-1977900 -Node: MPFR features978005 -Node: FP Math Caution979723 -Ref: FP Math Caution-Footnote-1980795 -Node: Inexactness of computations981164 -Node: Inexact representation982124 -Node: Comparing FP Values983484 -Node: Errors accumulate984725 -Node: Getting Accuracy986158 -Node: Try To Round988868 -Node: Setting precision989767 -Ref: table-predefined-precision-strings990464 -Node: Setting the rounding mode992294 -Ref: table-gawk-rounding-modes992668 -Ref: Setting the rounding mode-Footnote-1996599 -Node: Arbitrary Precision Integers996778 -Ref: Arbitrary Precision Integers-Footnote-1999953 -Node: Checking for MPFR1000102 -Node: POSIX Floating Point Problems1001576 -Ref: POSIX Floating Point Problems-Footnote-11005861 -Node: Floating point summary1005899 -Node: Dynamic Extensions1008089 -Node: Extension Intro1009642 -Node: Plugin License1010908 -Node: Extension Mechanism Outline1011705 -Ref: figure-load-extension1012144 -Ref: figure-register-new-function1013709 -Ref: figure-call-new-function1014801 -Node: Extension API Description1016863 -Node: Extension API Functions Introduction1018576 -Ref: table-api-std-headers1020412 -Node: General Data Types1024661 -Ref: General Data Types-Footnote-11033291 -Node: Memory Allocation Functions1033590 -Ref: Memory Allocation Functions-Footnote-11038091 -Node: Constructor Functions1038190 -Node: API Ownership of MPFR and GMP Values1041656 -Node: Registration Functions1042969 -Node: Extension Functions1043669 -Node: Exit Callback Functions1048991 -Node: Extension Version String1050241 -Node: Input Parsers1050904 -Node: Output Wrappers1063625 -Node: Two-way processors1068137 -Node: Printing Messages1070402 -Ref: Printing Messages-Footnote-11071573 -Node: Updating ERRNO1071726 -Node: Requesting Values1072465 -Ref: table-value-types-returned1073202 -Node: Accessing Parameters1074138 -Node: Symbol Table Access1075375 -Node: Symbol table by name1075887 -Ref: Symbol table by name-Footnote-11078911 -Node: Symbol table by cookie1079039 -Ref: Symbol table by cookie-Footnote-11083224 -Node: Cached values1083288 -Ref: Cached values-Footnote-11086824 -Node: Array Manipulation1086977 -Ref: Array Manipulation-Footnote-11088068 -Node: Array Data Types1088105 -Ref: Array Data Types-Footnote-11090763 -Node: Array Functions1090855 -Node: Flattening Arrays1095353 -Node: Creating Arrays1102329 -Node: Redirection API1107096 -Node: Extension API Variables1109929 -Node: Extension Versioning1110640 -Ref: gawk-api-version1111069 -Node: Extension GMP/MPFR Versioning1112800 -Node: Extension API Informational Variables1114428 -Node: Extension API Boilerplate1115501 -Node: Changes from API V11119475 -Node: Finding Extensions1121047 -Node: Extension Example1121606 -Node: Internal File Description1122404 -Node: Internal File Ops1126484 -Ref: Internal File Ops-Footnote-11137834 -Node: Using Internal File Ops1137974 -Ref: Using Internal File Ops-Footnote-11140357 -Node: Extension Samples1140631 -Node: Extension Sample File Functions1142160 -Node: Extension Sample Fnmatch1149809 -Node: Extension Sample Fork1151296 -Node: Extension Sample Inplace1152514 -Node: Extension Sample Ord1156140 -Node: Extension Sample Readdir1156976 -Ref: table-readdir-file-types1157865 -Node: Extension Sample Revout1158932 -Node: Extension Sample Rev2way1159521 -Node: Extension Sample Read write array1160261 -Node: Extension Sample Readfile1162203 -Node: Extension Sample Time1163298 -Node: Extension Sample API Tests1165050 -Node: gawkextlib1165542 -Node: Extension summary1168460 -Node: Extension Exercises1172162 -Node: Language History1173404 -Node: V7/SVR3.11175060 -Node: SVR41177212 -Node: POSIX1178646 -Node: BTL1180027 -Node: POSIX/GNU1180756 -Node: Feature History1186534 -Node: Common Extensions1202853 -Node: Ranges and Locales1204136 -Ref: Ranges and Locales-Footnote-11208752 -Ref: Ranges and Locales-Footnote-21208779 -Ref: Ranges and Locales-Footnote-31209014 -Node: Contributors1209237 -Node: History summary1215234 -Node: Installation1216614 -Node: Gawk Distribution1217558 -Node: Getting1218042 -Node: Extracting1219005 -Node: Distribution contents1220643 -Node: Unix Installation1227123 -Node: Quick Installation1227805 -Node: Shell Startup Files1230219 -Node: Additional Configuration Options1231308 -Node: Configuration Philosophy1233623 -Node: Non-Unix Installation1235992 -Node: PC Installation1236452 -Node: PC Binary Installation1237290 -Node: PC Compiling1237725 -Node: PC Using1238842 -Node: Cygwin1242395 -Node: MSYS1243619 -Node: VMS Installation1244221 -Node: VMS Compilation1245012 -Ref: VMS Compilation-Footnote-11246241 -Node: VMS Dynamic Extensions1246299 -Node: VMS Installation Details1247984 -Node: VMS Running1250237 -Node: VMS GNV1254516 -Node: VMS Old Gawk1255251 -Node: Bugs1255722 -Node: Bug address1256385 -Node: Usenet1259367 -Node: Maintainers1260371 -Node: Other Versions1261556 -Node: Installation summary1268644 -Node: Notes1269853 -Node: Compatibility Mode1270647 -Node: Additions1271429 -Node: Accessing The Source1272354 -Node: Adding Code1273791 -Node: New Ports1280010 -Node: Derived Files1284385 -Ref: Derived Files-Footnote-11290045 -Ref: Derived Files-Footnote-21290080 -Ref: Derived Files-Footnote-31290678 -Node: Future Extensions1290792 -Node: Implementation Limitations1291450 -Node: Extension Design1292660 -Node: Old Extension Problems1293804 -Ref: Old Extension Problems-Footnote-11295322 -Node: Extension New Mechanism Goals1295379 -Ref: Extension New Mechanism Goals-Footnote-11298743 -Node: Extension Other Design Decisions1298932 -Node: Extension Future Growth1301045 -Node: Notes summary1301651 -Node: Basic Concepts1302809 -Node: Basic High Level1303490 -Ref: figure-general-flow1303772 -Ref: figure-process-flow1304457 -Ref: Basic High Level-Footnote-11307758 -Node: Basic Data Typing1307943 -Node: Glossary1311271 -Node: Copying1343156 -Node: GNU Free Documentation License1380699 -Node: Index1405819 +Node: Naming Standard Input142473 +Node: Environment Variables143683 +Node: AWKPATH Variable144241 +Ref: AWKPATH Variable-Footnote-1147653 +Ref: AWKPATH Variable-Footnote-2147687 +Node: AWKLIBPATH Variable148058 +Ref: AWKLIBPATH Variable-Footnote-1149755 +Node: Other Environment Variables150130 +Node: Exit Status153951 +Node: Include Files154628 +Node: Loading Shared Libraries158318 +Node: Obsolete159746 +Node: Undocumented160438 +Node: Invoking Summary160735 +Node: Regexp163576 +Node: Regexp Usage165030 +Node: Escape Sequences167067 +Node: Regexp Operators173308 +Node: Regexp Operator Details173793 +Ref: Regexp Operator Details-Footnote-1180225 +Node: Interval Expressions180372 +Ref: Interval Expressions-Footnote-1181793 +Node: Bracket Expressions181891 +Ref: table-char-classes184367 +Node: Leftmost Longest187693 +Node: Computed Regexps188996 +Node: GNU Regexp Operators192423 +Node: Case-sensitivity196160 +Ref: Case-sensitivity-Footnote-1199026 +Ref: Case-sensitivity-Footnote-2199261 +Node: Regexp Summary199369 +Node: Reading Files200835 +Node: Records203104 +Node: awk split records204179 +Node: gawk split records209454 +Ref: gawk split records-Footnote-1214187 +Node: Fields214224 +Node: Nonconstant Fields216965 +Ref: Nonconstant Fields-Footnote-1219201 +Node: Changing Fields219405 +Node: Field Separators225436 +Node: Default Field Splitting228134 +Node: Regexp Field Splitting229252 +Node: Single Character Fields232605 +Node: Command Line Field Separator233665 +Node: Full Line Fields236883 +Ref: Full Line Fields-Footnote-1238405 +Ref: Full Line Fields-Footnote-2238451 +Node: Field Splitting Summary238552 +Node: Constant Size240626 +Node: Fixed width data241358 +Node: Skipping intervening244825 +Node: Allowing trailing data245623 +Node: Fields with fixed data246660 +Node: Splitting By Content248178 +Ref: Splitting By Content-Footnote-1251961 +Node: More CSV252124 +Node: Testing field creation253434 +Node: Multiple Line255059 +Node: Getline261336 +Node: Plain Getline263805 +Node: Getline/Variable266378 +Node: Getline/File267529 +Node: Getline/Variable/File268917 +Ref: Getline/Variable/File-Footnote-1270522 +Node: Getline/Pipe270610 +Node: Getline/Variable/Pipe273314 +Node: Getline/Coprocess274449 +Node: Getline/Variable/Coprocess275716 +Node: Getline Notes276458 +Node: Getline Summary279255 +Ref: table-getline-variants279679 +Node: Read Timeout280427 +Ref: Read Timeout-Footnote-1284333 +Node: Retrying Input284391 +Node: Command-line directories285590 +Node: Input Summary286496 +Node: Input Exercises289668 +Node: Printing290102 +Node: Print291936 +Node: Print Examples293393 +Node: Output Separators296173 +Node: OFMT298190 +Node: Printf299546 +Node: Basic Printf300331 +Node: Control Letters301905 +Node: Format Modifiers307069 +Node: Printf Examples313084 +Node: Redirection315570 +Node: Special FD322411 +Ref: Special FD-Footnote-1325579 +Node: Special Files325653 +Node: Other Inherited Files326270 +Node: Special Network327271 +Node: Special Caveats328131 +Node: Close Files And Pipes329080 +Ref: table-close-pipe-return-values335987 +Ref: Close Files And Pipes-Footnote-1336800 +Ref: Close Files And Pipes-Footnote-2336948 +Node: Nonfatal337100 +Node: Output Summary339438 +Node: Output Exercises340660 +Node: Expressions341339 +Node: Values342527 +Node: Constants343205 +Node: Scalar Constants343896 +Ref: Scalar Constants-Footnote-1346406 +Node: Nondecimal-numbers346656 +Node: Regexp Constants349657 +Node: Using Constant Regexps350183 +Node: Standard Regexp Constants350805 +Node: Strong Regexp Constants353993 +Node: Variables357005 +Node: Using Variables357662 +Node: Assignment Options359572 +Node: Conversion362043 +Node: Strings And Numbers362567 +Ref: Strings And Numbers-Footnote-1365630 +Node: Locale influences conversions365739 +Ref: table-locale-affects368497 +Node: All Operators369115 +Node: Arithmetic Ops369744 +Node: Concatenation372460 +Ref: Concatenation-Footnote-1375307 +Node: Assignment Ops375414 +Ref: table-assign-ops380405 +Node: Increment Ops381718 +Node: Truth Values and Conditions385178 +Node: Truth Values386252 +Node: Typing and Comparison387300 +Node: Variable Typing388120 +Ref: Variable Typing-Footnote-1394583 +Ref: Variable Typing-Footnote-2394655 +Node: Comparison Operators394732 +Ref: table-relational-ops395151 +Node: POSIX String Comparison398646 +Ref: POSIX String Comparison-Footnote-1400341 +Ref: POSIX String Comparison-Footnote-2400480 +Node: Boolean Ops400564 +Ref: Boolean Ops-Footnote-1405046 +Node: Conditional Exp405138 +Node: Function Calls406874 +Node: Precedence410751 +Node: Locales414410 +Node: Expressions Summary416042 +Node: Patterns and Actions418615 +Node: Pattern Overview419735 +Node: Regexp Patterns421412 +Node: Expression Patterns421954 +Node: Ranges425735 +Node: BEGIN/END428843 +Node: Using BEGIN/END429604 +Ref: Using BEGIN/END-Footnote-1432358 +Node: I/O And BEGIN/END432464 +Node: BEGINFILE/ENDFILE434777 +Node: Empty438008 +Node: Using Shell Variables438325 +Node: Action Overview440599 +Node: Statements442924 +Node: If Statement444772 +Node: While Statement446267 +Node: Do Statement448295 +Node: For Statement449443 +Node: Switch Statement452614 +Node: Break Statement455055 +Node: Continue Statement457147 +Node: Next Statement458974 +Node: Nextfile Statement461357 +Node: Exit Statement464009 +Node: Built-in Variables466412 +Node: User-modified467545 +Node: Auto-set475312 +Ref: Auto-set-Footnote-1492119 +Ref: Auto-set-Footnote-2492325 +Node: ARGC and ARGV492381 +Node: Pattern Action Summary496594 +Node: Arrays499024 +Node: Array Basics500353 +Node: Array Intro501197 +Ref: figure-array-elements503172 +Ref: Array Intro-Footnote-1505876 +Node: Reference to Elements506004 +Node: Assigning Elements508468 +Node: Array Example508959 +Node: Scanning an Array510718 +Node: Controlling Scanning513740 +Ref: Controlling Scanning-Footnote-1520196 +Node: Numeric Array Subscripts520512 +Node: Uninitialized Subscripts522696 +Node: Delete524315 +Ref: Delete-Footnote-1527067 +Node: Multidimensional527124 +Node: Multiscanning530219 +Node: Arrays of Arrays531810 +Node: Arrays Summary536578 +Node: Functions538671 +Node: Built-in539709 +Node: Calling Built-in540790 +Node: Numeric Functions542786 +Ref: Numeric Functions-Footnote-1546814 +Ref: Numeric Functions-Footnote-2547462 +Ref: Numeric Functions-Footnote-3547510 +Node: String Functions547782 +Ref: String Functions-Footnote-1571923 +Ref: String Functions-Footnote-2572051 +Ref: String Functions-Footnote-3572299 +Node: Gory Details572386 +Ref: table-sub-escapes574177 +Ref: table-sub-proposed575696 +Ref: table-posix-sub577059 +Ref: table-gensub-escapes578600 +Ref: Gory Details-Footnote-1579423 +Node: I/O Functions579577 +Ref: table-system-return-values586031 +Ref: I/O Functions-Footnote-1588111 +Ref: I/O Functions-Footnote-2588259 +Node: Time Functions588379 +Ref: Time Functions-Footnote-1599050 +Ref: Time Functions-Footnote-2599118 +Ref: Time Functions-Footnote-3599276 +Ref: Time Functions-Footnote-4599387 +Ref: Time Functions-Footnote-5599499 +Ref: Time Functions-Footnote-6599726 +Node: Bitwise Functions599992 +Ref: table-bitwise-ops600586 +Ref: Bitwise Functions-Footnote-1606649 +Ref: Bitwise Functions-Footnote-2606822 +Node: Type Functions607013 +Node: I18N Functions609876 +Node: User-defined611527 +Node: Definition Syntax612339 +Ref: Definition Syntax-Footnote-1618033 +Node: Function Example618104 +Ref: Function Example-Footnote-1621026 +Node: Function Calling621048 +Node: Calling A Function621636 +Node: Variable Scope622594 +Node: Pass By Value/Reference625588 +Node: Function Caveats628232 +Ref: Function Caveats-Footnote-1630279 +Node: Return Statement630399 +Node: Dynamic Typing633378 +Node: Indirect Calls634308 +Ref: Indirect Calls-Footnote-1644560 +Node: Functions Summary644688 +Node: Library Functions647393 +Ref: Library Functions-Footnote-1651000 +Ref: Library Functions-Footnote-2651143 +Node: Library Names651314 +Ref: Library Names-Footnote-1654981 +Ref: Library Names-Footnote-2655204 +Node: General Functions655290 +Node: Strtonum Function656393 +Node: Assert Function659415 +Node: Round Function662741 +Node: Cliff Random Function664281 +Node: Ordinal Functions665297 +Ref: Ordinal Functions-Footnote-1668360 +Ref: Ordinal Functions-Footnote-2668612 +Node: Join Function668822 +Ref: Join Function-Footnote-1670592 +Node: Getlocaltime Function670792 +Node: Readfile Function674534 +Node: Shell Quoting676511 +Node: Data File Management677912 +Node: Filetrans Function678544 +Node: Rewind Function682640 +Node: File Checking684549 +Ref: File Checking-Footnote-1685883 +Node: Empty Files686084 +Node: Ignoring Assigns688063 +Node: Getopt Function689613 +Ref: Getopt Function-Footnote-1704824 +Node: Passwd Functions705024 +Ref: Passwd Functions-Footnote-1713863 +Node: Group Functions713951 +Ref: Group Functions-Footnote-1721849 +Node: Walking Arrays722056 +Node: Library Functions Summary725064 +Node: Library Exercises726470 +Node: Sample Programs726935 +Node: Running Examples727705 +Node: Clones728433 +Node: Cut Program729657 +Node: Egrep Program739586 +Node: Id Program748597 +Node: Split Program758544 +Ref: Split Program-Footnote-1768318 +Node: Tee Program768491 +Node: Uniq Program771281 +Node: Wc Program778845 +Node: Bytes vs. Characters779242 +Node: Using extensions780790 +Node: wc program781548 +Node: Miscellaneous Programs786413 +Node: Dupword Program787626 +Node: Alarm Program789656 +Node: Translate Program794511 +Ref: Translate Program-Footnote-1799076 +Node: Labels Program799346 +Ref: Labels Program-Footnote-1802697 +Node: Word Sorting802781 +Node: History Sorting806853 +Node: Extract Program809078 +Node: Simple Sed817132 +Node: Igawk Program820206 +Ref: Igawk Program-Footnote-1834537 +Ref: Igawk Program-Footnote-2834739 +Ref: Igawk Program-Footnote-3834861 +Node: Anagram Program834976 +Node: Signature Program838038 +Node: Programs Summary839285 +Node: Programs Exercises840499 +Ref: Programs Exercises-Footnote-1844629 +Node: Advanced Features844715 +Node: Nondecimal Data846705 +Node: Array Sorting848296 +Node: Controlling Array Traversal848996 +Ref: Controlling Array Traversal-Footnote-1857364 +Node: Array Sorting Functions857482 +Ref: Array Sorting Functions-Footnote-1862573 +Node: Two-way I/O862769 +Ref: Two-way I/O-Footnote-1870490 +Ref: Two-way I/O-Footnote-2870677 +Node: TCP/IP Networking870759 +Node: Profiling873877 +Node: Advanced Features Summary883191 +Node: Internationalization885035 +Node: I18N and L10N886515 +Node: Explaining gettext887202 +Ref: Explaining gettext-Footnote-1893094 +Ref: Explaining gettext-Footnote-2893279 +Node: Programmer i18n893444 +Ref: Programmer i18n-Footnote-1898393 +Node: Translator i18n898442 +Node: String Extraction899236 +Ref: String Extraction-Footnote-1900368 +Node: Printf Ordering900454 +Ref: Printf Ordering-Footnote-1903240 +Node: I18N Portability903304 +Ref: I18N Portability-Footnote-1905760 +Node: I18N Example905823 +Ref: I18N Example-Footnote-1909098 +Ref: I18N Example-Footnote-2909171 +Node: Gawk I18N909280 +Node: I18N Summary909929 +Node: Debugger911270 +Node: Debugging912270 +Node: Debugging Concepts912711 +Node: Debugging Terms914520 +Node: Awk Debugging917095 +Ref: Awk Debugging-Footnote-1918040 +Node: Sample Debugging Session918172 +Node: Debugger Invocation918706 +Node: Finding The Bug920092 +Node: List of Debugger Commands926566 +Node: Breakpoint Control927899 +Node: Debugger Execution Control931593 +Node: Viewing And Changing Data934955 +Node: Execution Stack938496 +Node: Debugger Info940133 +Node: Miscellaneous Debugger Commands944204 +Node: Readline Support949266 +Node: Limitations950162 +Node: Debugging Summary952716 +Node: Namespaces953995 +Node: Global Namespace955106 +Node: Qualified Names956504 +Node: Default Namespace957503 +Node: Changing The Namespace958244 +Node: Naming Rules959858 +Node: Internal Name Management961706 +Node: Namespace Example962748 +Node: Namespace And Features965310 +Node: Namespace Summary966745 +Node: Arbitrary Precision Arithmetic968222 +Node: Computer Arithmetic969709 +Ref: table-numeric-ranges973475 +Ref: table-floating-point-ranges973968 +Ref: Computer Arithmetic-Footnote-1974626 +Node: Math Definitions974683 +Ref: table-ieee-formats977999 +Ref: Math Definitions-Footnote-1978602 +Node: MPFR features978707 +Node: FP Math Caution980425 +Ref: FP Math Caution-Footnote-1981497 +Node: Inexactness of computations981866 +Node: Inexact representation982826 +Node: Comparing FP Values984186 +Node: Errors accumulate985427 +Node: Getting Accuracy986860 +Node: Try To Round989570 +Node: Setting precision990469 +Ref: table-predefined-precision-strings991166 +Node: Setting the rounding mode992996 +Ref: table-gawk-rounding-modes993370 +Ref: Setting the rounding mode-Footnote-1997301 +Node: Arbitrary Precision Integers997480 +Ref: Arbitrary Precision Integers-Footnote-11000655 +Node: Checking for MPFR1000804 +Node: POSIX Floating Point Problems1002278 +Ref: POSIX Floating Point Problems-Footnote-11006563 +Node: Floating point summary1006601 +Node: Dynamic Extensions1008791 +Node: Extension Intro1010344 +Node: Plugin License1011610 +Node: Extension Mechanism Outline1012407 +Ref: figure-load-extension1012846 +Ref: figure-register-new-function1014411 +Ref: figure-call-new-function1015503 +Node: Extension API Description1017565 +Node: Extension API Functions Introduction1019278 +Ref: table-api-std-headers1021114 +Node: General Data Types1025363 +Ref: General Data Types-Footnote-11033993 +Node: Memory Allocation Functions1034292 +Ref: Memory Allocation Functions-Footnote-11038793 +Node: Constructor Functions1038892 +Node: API Ownership of MPFR and GMP Values1042358 +Node: Registration Functions1043671 +Node: Extension Functions1044371 +Node: Exit Callback Functions1049693 +Node: Extension Version String1050943 +Node: Input Parsers1051606 +Node: Output Wrappers1064327 +Node: Two-way processors1068839 +Node: Printing Messages1071104 +Ref: Printing Messages-Footnote-11072275 +Node: Updating ERRNO1072428 +Node: Requesting Values1073167 +Ref: table-value-types-returned1073904 +Node: Accessing Parameters1074840 +Node: Symbol Table Access1076077 +Node: Symbol table by name1076589 +Ref: Symbol table by name-Footnote-11079613 +Node: Symbol table by cookie1079741 +Ref: Symbol table by cookie-Footnote-11083926 +Node: Cached values1083990 +Ref: Cached values-Footnote-11087526 +Node: Array Manipulation1087679 +Ref: Array Manipulation-Footnote-11088770 +Node: Array Data Types1088807 +Ref: Array Data Types-Footnote-11091465 +Node: Array Functions1091557 +Node: Flattening Arrays1096055 +Node: Creating Arrays1103031 +Node: Redirection API1107798 +Node: Extension API Variables1110631 +Node: Extension Versioning1111342 +Ref: gawk-api-version1111771 +Node: Extension GMP/MPFR Versioning1113502 +Node: Extension API Informational Variables1115130 +Node: Extension API Boilerplate1116203 +Node: Changes from API V11120177 +Node: Finding Extensions1121749 +Node: Extension Example1122308 +Node: Internal File Description1123106 +Node: Internal File Ops1127186 +Ref: Internal File Ops-Footnote-11138536 +Node: Using Internal File Ops1138676 +Ref: Using Internal File Ops-Footnote-11141059 +Node: Extension Samples1141333 +Node: Extension Sample File Functions1142862 +Node: Extension Sample Fnmatch1150511 +Node: Extension Sample Fork1151998 +Node: Extension Sample Inplace1153216 +Node: Extension Sample Ord1156842 +Node: Extension Sample Readdir1157678 +Ref: table-readdir-file-types1158567 +Node: Extension Sample Revout1159634 +Node: Extension Sample Rev2way1160223 +Node: Extension Sample Read write array1160963 +Node: Extension Sample Readfile1162905 +Node: Extension Sample Time1164000 +Node: Extension Sample API Tests1165752 +Node: gawkextlib1166244 +Node: Extension summary1169162 +Node: Extension Exercises1172864 +Node: Language History1174106 +Node: V7/SVR3.11175762 +Node: SVR41177914 +Node: POSIX1179348 +Node: BTL1180729 +Node: POSIX/GNU1181458 +Node: Feature History1187236 +Node: Common Extensions1203555 +Node: Ranges and Locales1204838 +Ref: Ranges and Locales-Footnote-11209454 +Ref: Ranges and Locales-Footnote-21209481 +Ref: Ranges and Locales-Footnote-31209716 +Node: Contributors1209939 +Node: History summary1215936 +Node: Installation1217316 +Node: Gawk Distribution1218260 +Node: Getting1218744 +Node: Extracting1219707 +Node: Distribution contents1221345 +Node: Unix Installation1227825 +Node: Quick Installation1228507 +Node: Shell Startup Files1230921 +Node: Additional Configuration Options1232010 +Node: Configuration Philosophy1234325 +Node: Non-Unix Installation1236694 +Node: PC Installation1237154 +Node: PC Binary Installation1237992 +Node: PC Compiling1238427 +Node: PC Using1239544 +Node: Cygwin1243097 +Node: MSYS1244321 +Node: VMS Installation1244923 +Node: VMS Compilation1245714 +Ref: VMS Compilation-Footnote-11246943 +Node: VMS Dynamic Extensions1247001 +Node: VMS Installation Details1248686 +Node: VMS Running1250939 +Node: VMS GNV1255218 +Node: VMS Old Gawk1255953 +Node: Bugs1256424 +Node: Bug address1257087 +Node: Usenet1260069 +Node: Maintainers1261073 +Node: Other Versions1262258 +Node: Installation summary1269346 +Node: Notes1270555 +Node: Compatibility Mode1271349 +Node: Additions1272131 +Node: Accessing The Source1273056 +Node: Adding Code1274493 +Node: New Ports1280712 +Node: Derived Files1285087 +Ref: Derived Files-Footnote-11290747 +Ref: Derived Files-Footnote-21290782 +Ref: Derived Files-Footnote-31291380 +Node: Future Extensions1291494 +Node: Implementation Limitations1292152 +Node: Extension Design1293362 +Node: Old Extension Problems1294506 +Ref: Old Extension Problems-Footnote-11296024 +Node: Extension New Mechanism Goals1296081 +Ref: Extension New Mechanism Goals-Footnote-11299445 +Node: Extension Other Design Decisions1299634 +Node: Extension Future Growth1301747 +Node: Notes summary1302353 +Node: Basic Concepts1303511 +Node: Basic High Level1304192 +Ref: figure-general-flow1304474 +Ref: figure-process-flow1305159 +Ref: Basic High Level-Footnote-11308460 +Node: Basic Data Typing1308645 +Node: Glossary1311973 +Node: Copying1343858 +Node: GNU Free Documentation License1381401 +Node: Index1406521 End Tag Table diff --git a/doc/gawk.texi b/doc/gawk.texi index 0dc7a037..2a1e65c3 100644 --- a/doc/gawk.texi +++ b/doc/gawk.texi @@ -4532,6 +4532,80 @@ Given the variable assignment feature, the @option{-F} option for setting the value of @code{FS} is not strictly necessary. It remains for historical compatibility. +@cindex sidebar @subentry Quoting Shell Variables On The @command{awk} Command Line +@ifdocbook +@docbook +<sidebar><title>Quoting Shell Variables On The @command{awk} Command Line</title> +@end docbook + +@cindex quoting @subentry in @command{gawk} command lines +@cindex shell quoting, rules for +@cindex null strings @subentry in @command{gawk} arguments, quoting and + +Small @command{awk} programs are often embedded in larger shell scripts, +so it's worthwhile to understand some shell basics. Consider the following: + +@example +f="" +awk '@{ print("hi") @}' $f +@end example + +In this case, @command{awk} reads from standard input instead of trying +to open any command line files. To the unwary, this looks like @command{awk} +is hanging. + +However @command{awk} doesn't see an explicit empty string. When a +variable expansion is the null string, @emph{and} it's not quoted, +the shell simply removes it from the command line. To demonstrate: + +@example +$ @kbd{f=""} +$ @kbd{awk 'BEGIN @{ print ARGC @}' $f} +@print{} 1 +$ @kbd{awk 'BEGIN @{ print ARGC @}' "$f"} +@print{} 2 +@end example + +@docbook +</sidebar> +@end docbook +@end ifdocbook + +@ifnotdocbook +@cartouche +@center @b{Quoting Shell Variables On The @command{awk} Command Line} + + +@cindex quoting @subentry in @command{gawk} command lines +@cindex shell quoting, rules for +@cindex null strings @subentry in @command{gawk} arguments, quoting and + +Small @command{awk} programs are often embedded in larger shell scripts, +so it's worthwhile to understand some shell basics. Consider the following: + +@example +f="" +awk '@{ print("hi") @}' $f +@end example + +In this case, @command{awk} reads from standard input instead of trying +to open any command line files. To the unwary, this looks like @command{awk} +is hanging. + +However @command{awk} doesn't see an explicit empty string. When a +variable expansion is the null string, @emph{and} it's not quoted, +the shell simply removes it from the command line. To demonstrate: + +@example +$ @kbd{f=""} +$ @kbd{awk 'BEGIN @{ print ARGC @}' $f} +@print{} 1 +$ @kbd{awk 'BEGIN @{ print ARGC @}' "$f"} +@print{} 2 +@end example +@end cartouche +@end ifnotdocbook + @node Naming Standard Input @section Naming Standard Input diff --git a/doc/gawktexi.in b/doc/gawktexi.in index b584181d..e733c4ec 100644 --- a/doc/gawktexi.in +++ b/doc/gawktexi.in @@ -4442,6 +4442,36 @@ Given the variable assignment feature, the @option{-F} option for setting the value of @code{FS} is not strictly necessary. It remains for historical compatibility. +@sidebar Quoting Shell Variables On The @command{awk} Command Line +@cindex quoting @subentry in @command{gawk} command lines +@cindex shell quoting, rules for +@cindex null strings @subentry in @command{gawk} arguments, quoting and + +Small @command{awk} programs are often embedded in larger shell scripts, +so it's worthwhile to understand some shell basics. Consider the following: + +@example +f="" +awk '@{ print("hi") @}' $f +@end example + +In this case, @command{awk} reads from standard input instead of trying +to open any command line files. To the unwary, this looks like @command{awk} +is hanging. + +However @command{awk} doesn't see an explicit empty string. When a +variable expansion is the null string, @emph{and} it's not quoted, +the shell simply removes it from the command line. To demonstrate: + +@example +$ @kbd{f=""} +$ @kbd{awk 'BEGIN @{ print ARGC @}' $f} +@print{} 1 +$ @kbd{awk 'BEGIN @{ print ARGC @}' "$f"} +@print{} 2 +@end example +@end sidebar + @node Naming Standard Input @section Naming Standard Input |