home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / gnu / gawk-2.15.5-bin.lha / info / gawk.info-6 (.txt) < prev    next >
GNU Info File  |  1994-07-11  |  49KB  |  906 lines
  1. This is Info file gawk.info, produced by Makeinfo-1.55 from the input
  2. file /gnu/src/amiga/gawk-2.15.5/gawk.texi.
  3.    This file documents `awk', a program that you can use to select
  4. particular records in a file and perform operations upon them.
  5.    This is Edition 0.15 of `The GAWK Manual',
  6. for the 2.15 version of the GNU implementation
  7. of AWK.
  8.    Copyright (C) 1989, 1991, 1992, 1993 Free Software Foundation, Inc.
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that
  14. the entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.    Permission is granted to copy and distribute translations of this
  17. manual into another language, under the above conditions for modified
  18. versions, except that this permission notice may be stated in a
  19. translation approved by the Foundation.
  20. File: gawk.info,  Node: I/O Functions,  Next: Time Functions,  Prev: String Functions,  Up: Built-in
  21. Built-in Functions for Input/Output
  22. ===================================
  23. `close(FILENAME)'
  24.      Close the file FILENAME, for input or output.  The argument may
  25.      alternatively be a shell command that was used for redirecting to
  26.      or from a pipe; then the pipe is closed.
  27.      *Note Closing Input Files and Pipes: Close Input, regarding closing
  28.      input files and pipes.  *Note Closing Output Files and Pipes:
  29.      Close Output, regarding closing output files and pipes.
  30. `system(COMMAND)'
  31.      The system function allows the user to execute operating system
  32.      commands and then return to the `awk' program.  The `system'
  33.      function executes the command given by the string COMMAND.  It
  34.      returns, as its value, the status returned by the command that was
  35.      executed.
  36.      For example, if the following fragment of code is put in your `awk'
  37.      program:
  38.           END {
  39.                system("mail -s 'awk run done' operator < /dev/null")
  40.           }
  41.      the system operator will be sent mail when the `awk' program
  42.      finishes processing input and begins its end-of-input processing.
  43.      Note that much the same result can be obtained by redirecting
  44.      `print' or `printf' into a pipe.  However, if your `awk' program
  45.      is interactive, `system' is useful for cranking up large
  46.      self-contained programs, such as a shell or an editor.
  47.      Some operating systems cannot implement the `system' function.
  48.      `system' causes a fatal error if it is not supported.
  49. Controlling Output Buffering with `system'
  50. ------------------------------------------
  51.    Many utility programs will "buffer" their output; they save
  52. information to be written to a disk file or terminal in memory, until
  53. there is enough to be written in one operation.  This is often more
  54. efficient than writing every little bit of information as soon as it is
  55. ready.  However, sometimes it is necessary to force a program to
  56. "flush" its buffers; that is, write the information to its destination,
  57. even if a buffer is not full.  You can do this from your `awk' program
  58. by calling `system' with a null string as its argument:
  59.      system("")   # flush output
  60. `gawk' treats this use of the `system' function as a special case, and
  61. is smart enough not to run a shell (or other command interpreter) with
  62. the empty command.  Therefore, with `gawk', this idiom is not only
  63. useful, it is efficient.  While this idiom should work with other `awk'
  64. implementations, it will not necessarily avoid starting an unnecessary
  65. shell.
  66. File: gawk.info,  Node: Time Functions,  Prev: I/O Functions,  Up: Built-in
  67. Functions for Dealing with Time Stamps
  68. ======================================
  69.    A common use for `awk' programs is the processing of log files.  Log
  70. files often contain time stamp information, indicating when a
  71. particular log record was written.  Many programs log their time stamp
  72. in the form returned by the `time' system call, which is the number of
  73. seconds since a particular epoch.  On POSIX systems, it is the number
  74. of seconds since Midnight, January 1, 1970, UTC.
  75.    In order to make it easier to process such log files, and to easily
  76. produce useful reports, `gawk' provides two functions for working with
  77. time stamps.  Both of these are `gawk' extensions; they are not
  78. specified in the POSIX standard, nor are they in any other known version
  79. of `awk'.
  80. `systime()'
  81.      This function returns the current time as the number of seconds
  82.      since the system epoch.  On POSIX systems, this is the number of
  83.      seconds since Midnight, January 1, 1970, UTC.  It may be a
  84.      different number on other systems.
  85. `strftime(FORMAT, TIMESTAMP)'
  86.      This function returns a string.  It is similar to the function of
  87.      the same name in the ANSI C standard library.  The time specified
  88.      by TIMESTAMP is used to produce a string, based on the contents of
  89.      the FORMAT string.
  90.    The `systime' function allows you to compare a time stamp from a log
  91. file with the current time of day.  In particular, it is easy to
  92. determine how long ago a particular record was logged.  It also allows
  93. you to produce log records using the "seconds since the epoch" format.
  94.    The `strftime' function allows you to easily turn a time stamp into
  95. human-readable information.  It is similar in nature to the `sprintf'
  96. function, copying non-format specification characters verbatim to the
  97. returned string, and substituting date and time values for format
  98. specifications in the FORMAT string.  If no TIMESTAMP argument is
  99. supplied, `gawk' will use the current time of day as the time stamp.
  100.    `strftime' is guaranteed by the ANSI C standard to support the
  101. following date format specifications:
  102.      The locale's abbreviated weekday name.
  103.      The locale's full weekday name.
  104.      The locale's abbreviated month name.
  105.      The locale's full month name.
  106.      The locale's "appropriate" date and time representation.
  107.      The day of the month as a decimal number (01-31).
  108.      The hour (24-hour clock) as a decimal number (00-23).
  109.      The hour (12-hour clock) as a decimal number (01-12).
  110.      The day of the year as a decimal number (001-366).
  111.      The month as a decimal number (01-12).
  112.      The minute as a decimal number (00-59).
  113.      The locale's equivalent of the AM/PM designations associated with
  114.      a 12-hour clock.
  115.      The second as a decimal number (00-61).  (Occasionally there are
  116.      minutes in a year with one or two leap seconds, which is why the
  117.      seconds can go from 0 all the way to 61.)
  118.      The week number of the year (the first Sunday as the first day of
  119.      week 1) as a decimal number (00-53).
  120.      The weekday as a decimal number (0-6).  Sunday is day 0.
  121.      The week number of the year (the first Monday as the first day of
  122.      week 1) as a decimal number (00-53).
  123.      The locale's "appropriate" date representation.
  124.      The locale's "appropriate" time representation.
  125.      The year without century as a decimal number (00-99).
  126.      The year with century as a decimal number.
  127.      The time zone name or abbreviation, or no characters if no time
  128.      zone is determinable.
  129.      A literal `%'.
  130.    If a conversion specifier is not one of the above, the behavior is
  131. undefined.  (This is because the ANSI standard for C leaves the
  132. behavior of the C version of `strftime' undefined, and `gawk' will use
  133. the system's version of `strftime' if it's there.  Typically, the
  134. conversion specifier will either not appear in the returned string, or
  135. it will appear literally.)
  136.    Informally, a "locale" is the geographic place in which a program is
  137. meant to run.  For example, a common way to abbreviate the date
  138. September 4, 1991 in the United States would be "9/4/91".  In many
  139. countries in Europe, however, it would be abbreviated "4.9.91".  Thus,
  140. the `%x' specification in a `"US"' locale might produce `9/4/91', while
  141. in a `"EUROPE"' locale, it might produce `4.9.91'.  The ANSI C standard
  142. defines a default `"C"' locale, which is an environment that is typical
  143. of what most C programmers are used to.
  144.    A public-domain C v