~vcs-imports/gawk/master : revision 408.9.29

53

@c applies to and all the info about who's publishing this edition

54

55

@c These apply across the board.

56

@set UPDATE-MONTH August, 2014

56

@set UPDATE-MONTH September, 2014

57

@set VERSION 4.1

58

@set PATCHLEVEL 1

58

@set PATCHLEVEL 2

59

60

@ifset FOR_PRINT

61

@set TITLE Effective AWK Programming

62

@end ifset

63

@ifclear FOR_PRINT

60

64

@set TITLE GAWK: Effective AWK Programming

65

@end ifclear

61

66

@set SUBTITLE A User's Guide for GNU Awk

62

67

@set EDITION 4.1

63

68

560

565

* Regexp Field Splitting:: Using regexps as the field separator.

561

566

* Single Character Fields:: Making each character a separate

562

567

field.

563

* Command Line Field Separator:: Setting @code{FS} from the

564

command line.

568

* Command Line Field Separator:: Setting @code{FS} from the command

569

line.

565

570

* Full Line Fields:: Making the full line be a single

566

571

field.

567

572

* Field Splitting Summary:: Some final points and a summary table.

605

610

* Printf Examples:: Several examples.

606

611

* Redirection:: How to redirect output to multiple

607

612

files and pipes.

613

* Special FD:: Special files for I/O.

608

614

* Special Files:: File name interpretation in

609

615

@command{gawk}. @command{gawk} allows

610

616

access to inherited file descriptors.

611

* Special FD:: Special files for I/O.

617

* Other Inherited Files:: Accessing other open files with

618

@command{gawk}.

612

619

* Special Network:: Special files for network

613

620

communications.

614

621

* Special Caveats:: Things to watch out for.

721

728

elements.

722

729

* Controlling Scanning:: Controlling the order in which arrays

723

730

are scanned.

724

* Delete:: The @code{delete} statement removes an

725

element from an array.

726

731

* Numeric Array Subscripts:: How to use numbers as subscripts in

727

732

@command{awk}.

728

733

* Uninitialized Subscripts:: Using Uninitialized variables as

729

734

subscripts.

735

* Delete:: The @code{delete} statement removes an

736

element from an array.

730

737

* Multidimensional:: Emulating multidimensional arrays in

731

738

@command{awk}.

732

739

* Multiscanning:: Scanning multidimensional arrays.

1088

1095

Weinberger, @cite{The AWK Programming Language}, Addison-Wesley,

1089

1096

1988. AWK's simple programming paradigm---find a pattern in the

1090

1097

input and then perform an action---often reduced complex or tedious

1091

data manipulations to few lines of code. I was excited to try my

1098

data manipulations to a few lines of code. I was excited to try my

1092

1099

hand at programming in AWK.

1093

1100

1094

1101

Alas, the @command{awk} on my computer was a limited version of the

1222

1229

<affiliation><jobtitle>Nof Ayalon</jobtitle></affiliation>

1223

1230

<affiliation><jobtitle>ISRAEL</jobtitle></affiliation>

1224

1231

</author>

1225

1232

<date>December, 2014</date>

1226

1233

</prefaceinfo>

1227

1234

@end docbook

1228

1235

1244

1251

by Brian Kernighan.

1245

1252

This means that all

1246

1253

properly written @command{awk} programs should work with @command{gawk}.

1247

Thus, we usually don't distinguish between @command{gawk} and other

1254

So most of the time, we don't distinguish between @command{gawk} and other

1248

1255

@command{awk} implementations.

1249

1256

1250

1257

@cindex @command{awk}, POSIX and, See Also POSIX @command{awk}

1291

1298

Perform simple network communications

1292

1299

1293

1300

@item

1294

Profile and debug @command{awk} programs.

1301

Profile and debug @command{awk} programs

1295

1302

1296

1303

@item

1297

Extend the language with functions written in C or C++.

1304

Extend the language with functions written in C or C++

1298

1305

@end itemize

1299

1306

1300

1307

This @value{DOCUMENT} teaches you about the @command{awk} language and

1301

1308

how you can use it effectively. You should already be familiar with basic

1302

system commands, such as @command{cat} and @command{ls},@footnote{These commands

1309

system commands, such as @command{cat} and @command{ls},@footnote{These utilities

1303

1310

are available on POSIX-compliant systems, as well as on traditional

1304

1311

Unix-based systems. If you are using some other operating system, you still need to

1305

1312

be familiar with the ideas of I/O redirection and pipes.} as well as basic shell

1321

1328

@ifclear FOR_PRINT

1322

1329

(all versions) and OS/2 PCs,

1323

1330

@end ifclear

1324

and OpenVMS.

1325

(Some other, obsolete systems to which @command{gawk} was once ported

1326

are no longer supported and the code for those systems

1327

has been removed.)

1331

and OpenVMS.@footnote{Some other, obsolete systems to which @command{gawk}

1332

was once ported are no longer supported and the code for those systems

1333

has been removed.}

1328

1334

1329

1335

@menu

1330

1336

* History:: The history of @command{gawk} and

1516

1522

1517

1523

Most of the time, the examples use complete @command{awk} programs.

1518

1524

Some of the more advanced sections show only the part of the @command{awk}

1519

program that illustrates the concept currently being described.

1525

program that illustrates the concept being described.

1520

1526

1521

1527

While this @value{DOCUMENT} is aimed principally at people who have not been

1522

1528

exposed

1574

1580

provides arrays of arrays.

1575

1581

1576

1582

@ref{Functions},

1577

describes the built-in functions @command{awk} and

1578

@command{gawk} provide, as well as how to define

1579

your own functions.

1583

describes the built-in functions @command{awk} and @command{gawk} provide,

1584

as well as how to define your own functions. It also discusses how

1585

@command{gawk} lets you call functions indirectly.

1580

1586

1581

1587

Part II shows how to use @command{awk} and @command{gawk} for problem solving.

1582

1588

There is lots of code here for you to read and learn from.

1649

1655

1650

1656

@uref{http://www.gnu.org/software/gawk/manual/html_node/Notes.html,

1651

1657

The appendix on implementation notes}

1652

describes how to disable @command{gawk}'s extensions, as

1653

well as how to contribute new code to @command{gawk},

1654

and some possible future directions for @command{gawk} development.

1658

describes how to disable @command{gawk}'s extensions, how to contribute

1659

new code to @command{gawk}, where to find information on some possible

1660

future directions for @command{gawk} development, and the design decisions

1661

behind the extension API.

1655

1662

1656

1663

@uref{http://www.gnu.org/software/gawk/manual/html_node/Basic-Concepts.html,

1657

1664

The appendix on basic concepts}

1669

1676

is the license that covers this @value{DOCUMENT}.

1670

1677

1671

1678

Some of the chapters have exercise sections; these have also been

1672

omitted from the print edition.

1679

omitted from the print edition but are available online.

1673

1680

@end ifset

1674

1681

1675

1682

@ifclear FOR_PRINT

1892

1899

the title @cite{The GNU Awk User's Guide}.

1893

1900

@ifset FOR_PRINT

1894

1901

SSC published two editions of the @value{DOCUMENT} under the

1895

title @cite{Effective awk Programming}, and in O'Reilly published

1902

title @cite{Effective awk Programming}, and O'Reilly published

1896

1903

the third edition in 2001.

1897

1904

@end ifset

1898

1905

1924

1931

@unnumberedsec How to Stay Current

1925

1932

1926

1933

It may be you have a version of @command{gawk} which is newer than the

1927

one described in this @value{DOCUMENT}. To find out what has changed,

1934

one described here. To find out what has changed,

1928

1935

you should first look at the @file{NEWS} file in the @command{gawk}

1929

1936

distribution, which provides a high level summary of what changed in

1930

1937

each release.

2146

2153

Arnold Robbins @*

2147

2154

Nof Ayalon @*

2148

2155

ISRAEL @*

2149

May, 2014

2156

December, 2014

2150

2157

@end iftex

2151

2158

2152

2159

@ifnotinfo

2365

2372

programming:

2366

2373

2367

2374

@example

2368

$ @kbd{awk "BEGIN @{ print "Don\47t Panic!" @}"}

2375

$ @kbd{awk 'BEGIN @{ print "Don\47t Panic!" @}'}

2369

2376

@print{} Don't Panic!

2370

2377

@end example

2371

2378

2373

2380

reading any input. If there are no other statements in your program,

2374

2381

as is the case here, @command{awk} just stops, instead of trying to read

2375

2382

input it doesn't know how to process.

2376

The @samp{\47} is a magic way of getting a single quote into

2383

The @samp{\47} is a magic way (explained later) of getting a single quote into

2377

2384

the program, without having to engage in ugly shell quoting tricks.

2378

2385

2379

2386

@quotation NOTE

2380

As a side note, if you use Bash as your shell, you should execute the

2387

If you use Bash as your shell, you should execute the

2381

2388

command @samp{set +H} before running this program interactively, to

2382

2389

disable the C shell-style command history, which treats @samp{!} as a

2383

2390

special character. We recommend putting this command into your personal

2407

2414

@cindex @command{awk} programs, running

2408

2415

@cindex @command{awk} programs, lengthy

2409

2416

@cindex files, @command{awk} programs in

2410

Sometimes your @command{awk} programs can be very long. In this case, it is

2417

Sometimes @command{awk} programs are very long. In these cases, it is

2411

2418

more convenient to put the program into a separate file. In order to tell

2412

2419

@command{awk} to use that file for its program, you type:

2413

2420

2437

2444

does the same thing as this one:

2438

2445

2439

2446

@example

2440

awk "BEGIN @{ print \"Don't Panic!\" @}"

2447

awk 'BEGIN @{ print "Don\47t Panic!" @}'

2441

2448

@end example

2442

2449

2443

2450

@cindex quoting in @command{gawk} command lines

2449

2456

special characters. Notice that in @file{advice}, the @command{awk}

2450

2457

program did not have single quotes around it. The quotes are only needed

2451

2458

for programs that are provided on the @command{awk} command line.

2459

(Also, placing the program in a file allows us to use a literal single quote in the program

2460

text, instead of the magic @samp{\47}.)

2452

2461

2453

2462

@c STARTOFRANGE sq1x

2454

2463

@cindex single quote (@code{'}) in @command{gawk} command lines

2512

2521

according to the instructions in your program. (This is different

2513

2522

from a @dfn{compiled} language such as C, where your program is first

2514

2523

compiled into machine code that is executed directly by your system's

2515

hardware.) The @command{awk} utility is thus termed an @dfn{interpreter}.

2524

processor.) The @command{awk} utility is thus termed an @dfn{interpreter}.

2516

2525

Many modern languages are interperted.

2517

2526

2518

2527

The line beginning with @samp{#!} lists the full @value{FN} of an

2521

2530

interpreter with the given argument and the full argument list of the

2522

2531

executed program. The first argument in the list is the full @value{FN}

2523

2532

of the @command{awk} program. The rest of the argument list contains

2524

either options to @command{awk}, or @value{DF}s, or both. Note that on

2533

either options to @command{awk}, or @value{DF}s, or both. (Note that on

2525

2534

many systems @command{awk} may be found in @file{/usr/bin} instead of

2526

in @file{/bin}. Caveat Emptor.

2535

in @file{/bin}.)

2527

2536

2528

2537

Some systems limit the length of the interpreter name to 32 characters.

2529

2538

Often, this can be dealt with by using a symbolic link.

2562

2571

according to the instructions in your program. (This is different

2563

2572

from a @dfn{compiled} language such as C, where your program is first

2564

2573

compiled into machine code that is executed directly by your system's

2565

hardware.) The @command{awk} utility is thus termed an @dfn{interpreter}.

2574

processor.) The @command{awk} utility is thus termed an @dfn{interpreter}.

2566

2575

Many modern languages are interperted.

2567

2576

2568

2577

The line beginning with @samp{#!} lists the full @value{FN} of an

2571

2580

interpreter with the given argument and the full argument list of the

2572

2581

executed program. The first argument in the list is the full @value{FN}

2573

2582

of the @command{awk} program. The rest of the argument list contains

2574

either options to @command{awk}, or @value{DF}s, or both. Note that on

2583

either options to @command{awk}, or @value{DF}s, or both. (Note that on

2575

2584

many systems @command{awk} may be found in @file{/usr/bin} instead of

2576

in @file{/bin}. Caveat Emptor.

2585

in @file{/bin}.)

2577

2586

2578

2587

Some systems limit the length of the interpreter name to 32 characters.

2579

2588

Often, this can be dealt with by using a symbolic link.

2752

2761

@ifnotinfo

2753

2762

previously

2754

2763

@end ifnotinfo

2755

in @ref{Read Terminal},

2756

is applicable:

2764

in @ref{Read Terminal}:

2765

2766

@example

2767

awk 'BEGIN @{ print "Don\47t Panic!" @}'

2768

@end example

2769

2770

@noindent

2771

could instead be written this way:

2757

2772

2758

2773

@example

2759

2774

$ @kbd{awk "BEGIN @{ print \"Don't Panic!\" @}"}

2848

2863

@print{} Here is a single quote <'>

2849

2864

@end example

2850

2865

2866

(Here, the two string constants and the value of @code{sq} are concatenated

2867

into a single string which is printed by @code{print}.)

2868

2851

2869

If you really need both single and double quotes in your @command{awk}

2852

2870

program, it is probably best to move it into a separate file, where

2853

2871

the shell won't be part of the picture, and you can say what you mean.

2911

2929

information about monthly shipments. In both files,

2912

2930

each line is considered to be one @dfn{record}.

2913

2931

2914

In the @value{DF} @file{mail-list}, each record contains the name of a person,

2932

In @file{mail-list}, each record contains the name of a person,

2915

2933

his/her phone number, his/her email-address, and a code for their relationship

2916

2934

with the author of the list.

2917

2935

The columns are aligned using spaces.

3071

3089

3072

3090

@example

3073

3091

expand data | awk '@{ if (x < length($0)) x = length($0) @}

3074

END @{ print "maximum line length is " x @}'

3092

END @{ print "maximum line length is " x @}'

3075

3093

@end example

3076

3094

3077

3095

This example differs slightly from the previous one:

3103

3121

3104

3122

@example

3105

3123

ls -l @var{files} | awk '@{ x += $5 @}

3106

END @{ print "total bytes: " x @}'

3124

END @{ print "total bytes: " x @}'

3107

3125

@end example

3108

3126

3109

3127

@item

3147

3165

@cindex @command{awk} programs

3148

3166

3149

3167

The @command{awk} utility reads the input files one line at a

3150

time. For each line, @command{awk} tries the patterns of each of the rules.

3168

time. For each line, @command{awk} tries the patterns of each rule.

3151

3169

If several patterns match, then several actions execute in the order in

3152

3170

which they appear in the @command{awk} program. If no patterns match, then

3153

3171

no actions run.

3155

3173

After processing all the rules that match the line (and perhaps there are none),

3156

3174

@command{awk} reads the next line. (However,

3157

3175

@pxref{Next Statement},

3158

and also @pxref{Nextfile Statement}).

3176

and also @pxref{Nextfile Statement}.)

3159

3177

This continues until the program reaches the end of the file.

3160

3178

For example, the following @command{awk} program contains two rules:

3161

3179

3229

3247

@noindent

3230

3248

@cindex line continuations, with C shell

3231

3249

The first field contains read-write permissions, the second field contains

3232

the number of links to the file, and the third field identifies the owner of

3233

the file. The fourth field identifies the group of the file.

3234

The fifth field contains the size of the file in bytes. The

3250

the number of links to the file, and the third field identifies the file's owner.

3251

The fourth field identifies the file's group.

3252

The fifth field contains the file's size in bytes. The

3235

3253

sixth, seventh, and eighth fields contain the month, day, and time,

3236

3254

respectively, that the file was last modified. Finally, the ninth field

3237

contains the @value{FN}.@footnote{The @samp{LC_ALL=C} is

3238

needed to produce this traditional-style output from @command{ls}.}

3255

contains the @value{FN}.

3239

3256

3240

3257

@c @cindex automatic initialization

3241

3258

@cindex initialization, automatic

3645

3662

Using @option{-v} to set the values of the built-in

3646

3663

variables may lead to surprising results. @command{awk} will reset the

3647

3664

values of those variables as it needs to, possibly ignoring any

3648

predefined value you may have given.

3665

initial value you may have given.

3649

3666

@end quotation

3650

3667

3651

3668

@item -W @var{gawk-opt}

3728

3745

@cindex variables, global, printing list of

3729

3746

Print a sorted list of global variables, their types, and final values

3730

3747

to @var{file}. If no @var{file} is provided, print this

3731

list to the file named @file{awkvars.out} in the current directory.

3748

list to a file named @file{awkvars.out} in the current directory.

3732

3749

No space is allowed between the @option{-d} and @var{file}, if

3733

3750

@var{file} is supplied.

3734

3751

3824

3841

@cindex @option{-i} option

3825

3842

@cindex @option{--include} option

3826

3843

@cindex @command{awk} programs, location of

3827

Read @command{awk} source library from @var{source-file}. This option

3844

Read an @command{awk} source library from @var{source-file}. This option

3828

3845

is completely equivalent to using the @code{@@include} directive inside

3829

3846

your program. This option is very similar to the @option{-f} option,

3830

3847

but there are two important differences. First, when @option{-i} is

3848

3865

supplied by default, so it need not be specified in the extension name.

3849

3866

The extension initialization routine should be named @code{dl_load()}.

3850

3867

An alternative is to use the @code{@@load} keyword inside the program to load

3851

a shared library. This feature is described in detail in @ref{Dynamic Extensions}.

3868

a shared library. This advanced feature is described in detail in @ref{Dynamic Extensions}.

3852

3869

3853

3870

@item @option{-L}[@var{value}]

3854

3871

@itemx @option{--lint}[@code{=}@var{value}]

3897

3914

@quotation CAUTION

3898

3915

This option can severely break old programs.

3899

3916

Use with care.

3917

3918

This option may disappear in a future version of @command{gawk}.

3900

3919

@end quotation

3901

3920

3902

3921

@item @option{-N}

4060

4079

useful for creating libraries of @command{awk} functions. These functions

4061

4080

can be written once and then retrieved from a standard place, instead

4062

4081

of having to be included into each individual program.

4082

The @option{-i} option is similar in this regard.

4063

4083

(As mentioned in

4064

4084

@ref{Definition Syntax},

4065

4085

function names must be unique.)

4133

4153

input files to be processed in the order specified. However, an

4134

4154

argument that has the form @code{@var{var}=@var{value}}, assigns

4135

4155

the value @var{value} to the variable @var{var}---it does not specify a

4136

file at all.

4137

(See

4138

@ref{Assignment Options}.)

4156

file at all. (See @ref{Assignment Options}.) In the following example,

4157

@var{count=1} is a variable assignment, not a @value{FN}:

4158

4159

@example

4160

awk -f program.awk file1 count=1 file2

4161

@end example

4139

4162

4140

4163

@cindex @command{gawk}, @code{ARGIND} variable in

4141

4164

@cindex @code{ARGIND} variable, command-line arguments

4142

4165

@cindex @code{ARGV} array, indexing into

4143

4166

@cindex @code{ARGC}/@code{ARGV} variables, command-line arguments

4144

All these arguments are made available to your @command{awk} program in the

4167

All the command-line arguments are made available to your @command{awk} program in the

4145

4168

@code{ARGV} array (@pxref{Built-in Variables}). Command-line options

4146

4169

and the program text (if present) are omitted from @code{ARGV}.

4147

4170

All other arguments, including variable assignments, are

4272

4295

@samp{.:/usr/local/share/awk}.@footnote{Your version of @command{gawk}

4273

4296

may use a different directory; it

4274

4297

will depend upon how @command{gawk} was built and installed. The actual

4275

directory is the value of @samp{$(datadir)} generated when

4298

directory is the value of @code{$(datadir)} generated when

4276

4299

@command{gawk} was configured. You probably don't need to worry about this,

4277

4300

though.}

4278

4301

4279

4302

The search path feature is particularly helpful for building libraries

4280

4303

of useful @command{awk} functions. The library files can be placed in a

4281

4304

standard directory in the default path and then specified on

4282

the command line with a short @value{FN}. Otherwise, the full @value{FN}

4283

would have to be typed for each file.

4305

the command line with a short @value{FN}. Otherwise, you would have to

4306

type the full @value{FN} for each file.

4284

4307

4285

4308

By using the @option{-i} option, or the @option{-e} and @option{-f} options, your command-line

4286

4309

@command{awk} programs can use facilities in @command{awk} library files

4289

4312

This is true for both @option{--traditional} and @option{--posix}.

4290

4313

@xref{Options}.

4291

4314

4292

If the source code is not found after the initial search, the path is searched

4315

If the source code file is not found after the initial search, the path is searched

4293

4316

again after adding the default @samp{.awk} suffix to the @value{FN}.

4294

4317

4295

@quotation NOTE

4296

@c 4/2014:

4297

@c using @samp{.} to get quotes, since @file{} no longer supplies them.

4298

To include

4299

the current directory in the path, either place

4300

@samp{.} explicitly in the path or write a null entry in the

4301

path. (A null entry is indicated by starting or ending the path with a

4302

colon or by placing two colons next to each other [@samp{::}].)

4303

This path search mechanism is similar

4318

@command{gawk}'s path search mechanism is similar

4304

4319

to the shell's.

4305

4320

(See @uref{http://www.gnu.org/software/bash/manual/,

4306

@cite{The Bourne-Again SHell manual}.})

4321

@cite{The Bourne-Again SHell manual}}.)

4322

It treats a null entry in the path as indicating the current

4323

directory.

4324

(A null entry is indicated by starting or ending the path with a

4325

colon or by placing two colons next to each other [@samp{::}].)

4307

4326

4308

However, @command{gawk} always looks in the current directory @emph{before}

4309

searching @env{AWKPATH}, so there is no real reason to include

4310

the current directory in the search path.

4327

@quotation NOTE

4328

@command{gawk} always looks in the current directory @emph{before}

4329

searching @env{AWKPATH}. Thus, while you can include the current directory

4330

in the search path, either explicitly or with a null entry, there is no

4331

real reason to do so.

4311

4332

@c Prior to 4.0, gawk searched the current directory after the

4312

4333

@c path search, but it's not worth documenting it.

4313

4334

@end quotation

4348

4369

list are meant to be used by regular users.

4349

4370

4350

4371

@table @env

4351

@item POSIXLY_CORRECT

4352

Causes @command{gawk} to switch to POSIX compatibility

4353

mode, disabling all traditional and GNU extensions.

4354

@xref{Options}.

4355

4356

@item GAWK_SOCK_RETRIES

4357

Controls the number of times @command{gawk} attempts to

4358

retry a two-way TCP/IP (socket) connection before giving up.

4359

@xref{TCP/IP Networking}.

4360

4361

4372

@item GAWK_MSEC_SLEEP

4362

4373

Specifies the interval between connection retries,

4363

4374

in milliseconds. On systems that do not support

4368

4379

Specifies the time, in milliseconds, for @command{gawk} to

4369

4380

wait for input before returning with an error.

4370

4381

@xref{Read Timeout}.

4382

4383

@item GAWK_SOCK_RETRIES

4384

Controls the number of times @command{gawk} attempts to

4385

retry a two-way TCP/IP (socket) connection before giving up.

4386

@xref{TCP/IP Networking}.

4387

4388

@item POSIXLY_CORRECT

4389

Causes @command{gawk} to switch to POSIX compatibility

4390

mode, disabling all traditional and GNU extensions.

4391

@xref{Options}.

4371

4392

@end table

4372

4393

4373

4394

The environment variables in the following list are meant

4382

4403

the value should be a number, and @command{gawk} uses that number as

4383

4404

the size of the buffer to allocate. (When this variable is not set,

4384

4405

@command{gawk} uses the smaller of the file's size and the ``default''

4385

blocksize, which is usually the filesystems I/O blocksize.)

4406

blocksize, which is usually the filesystem's I/O blocksize.)

4386

4407

4387

4408

@item AWK_HASH

4388

4409

If this variable exists with a value of @samp{gst}, @command{gawk}

4397

4418

where I/O is performed in records, not in blocks.

4398

4419

4399

4420

@item GAWK_MSG_SRC

4400

If this variable exists, @command{gawk} includes the source file

4401

name and line number from which warning and/or fatal messages

4421

If this variable exists, @command{gawk} includes the file

4422

name and line number within the @command{gawk} source code

4423

from which warning and/or fatal messages

4402

4424

are generated. Its purpose is to help isolate the source of a

4403

message, since there can be multiple places which produce the

4425

message, since there are multiple places which produce the

4404

4426

same warning or error message.

4405

4427

4406

4428

@item GAWK_NO_DFA

4613

4635

4614

4636

@ref{Dynamic Extensions}, describes how to write extensions (in C or C++)

4615

4637

that can be loaded with either @code{@@load} or the @option{-l} option.

4638

It also describes the @code{ordchr} extension.

4616

4639

4617

4640

@node Obsolete

4618

4641

@section Obsolete Options and/or Features

4681

4704

@end example

4682

4705

4683

4706

@command{gawk} actually supports this but it is purposely undocumented

4684

because it is considered bad style. The correct way to write such a program

4685

is either

4707

because it is bad style. The correct way to write such a program

4708

is either:

4686

4709

4687

4710

@example

4688

4711

awk '@{ sum += $1 @} ; END @{ print sum @}'

4689

4712

@end example

4690

4713

4691

4714

@noindent

4692

or

4715

or:

4693

4716

4694

4717

@example

4695

4718

awk '@{ sum += $1 @}

4697

4720

@end example

4698

4721

4699

4722

@noindent

4700

@xref{Statements/Lines}, for a fuller

4701

explanation.

4723

@xref{Statements/Lines}, for a fuller explanation.

4702

4724

4703

4725

You can insert newlines after the @samp{;} in @code{for} loops.

4704

4726

This seems to have been a long-undocumented feature in Unix @command{awk}.

4738

4760

4739

4761

@item

4740

4762

You can use a single minus sign (@samp{-}) to refer to standard input

4741

on the command line.

4763

on the command line. @command{gawk} also lets you use the special

4764

@value{FN} @file{/dev/stdin}.

4742

4765

4743

4766

@item

4744

4767

@command{gawk} pays attention to a number of environment variables.

4927

4950

unprintable characters directly in a string constant or regexp constant,

4928

4951

they may look ugly.

4929

4952

4930

The following table lists

4953

The following list presents

4931

4954

all the escape sequences used in @command{awk} and

4932

4955

what they represent. Unless noted otherwise, all these escape

4933

4956

sequences apply to both string constants and regexp constants:

5043

5066

@cindex @code{\} (backslash), in escape sequences

5044

5067

@cindex portability

5045

5068

For complete portability, do not use a backslash before any character not

5046

shown in the previous list.

5069

shown in the previous list and that is not an operator.

5047

5070

5048

5071

To summarize:

5049

5072

5050

5073

@itemize @value{BULLET}

5051

5074

@item

5052

The escape sequences in the table above are always processed first,

5075

The escape sequences in the list above are always processed first,

5053

5076

for both string constants and regexp constants. This happens very early,

5054

5077

as soon as @command{awk} reads your program.

5055

5078

5222

5245

the very first step in processing regexps.

5223

5246

5224

5247

Here is a list of metacharacters. All characters that are not escape

5225

sequences and that are not listed in the table stand for themselves:

5248

sequences and that are not listed in the following stand for themselves:

5226

5249

5227

5250

@c Use @asis so the docbook comes out ok. Sigh.

5228

5251

@table @asis

5479

5502

@cindex Extended Regular Expressions (EREs)

5480

5503

@cindex EREs (Extended Regular Expressions)

5481

5504

@cindex @command{egrep} utility

5482

This treatment of @samp{\} in bracket expressions

5505

The treatment of @samp{\} in bracket expressions

5483

5506

is compatible with other @command{awk}

5484

5507

implementations and is also mandated by POSIX.

5485

5508

The regular expressions in @command{awk} are a superset

5596

5619

echo aaaabcd | awk '@{ sub(/a+/, "<A>"); print @}'

5597

5620

@end example

5598

5621

5599

This example uses the @code{sub()} function (which we haven't discussed yet;

5600

@pxref{String Functions})

5601

to make a change to the input record. Here, the regexp @code{/a+/}

5602

indicates ``one or more @samp{a} characters,'' and the replacement

5603

text is @samp{<A>}.

5622

This example uses the @code{sub()} function to make a change to the input

5623

record. (@code{sub()} replaces the first instance of any text matched

5624

by the first argument with the string provided as the second argument;

5625

@pxref{String Functions}). Here, the regexp @code{/a+/} indicates ``one

5626

or more @samp{a} characters,'' and the replacement text is @samp{<A>}.

5604

5627

5605

5628

The input contains four @samp{a} characters.

5606

5629

@command{awk} (and POSIX) regular expressions always match

5716

5739

@cindex regular expressions, dynamic, with embedded newlines

5717

5740

@cindex newlines, in dynamic regexps

5718

5741

5719

Some versions of @command{awk} do not allow the newline

5742

Some older versions of @command{awk} do not allow the newline

5720

5743

character to be used inside a bracket expression for a dynamic regexp:

5721

5744

5722

5745

@example

5725

5748

@error{} ]...

5726

5749

@error{} source line number 1

5727

5750

@error{} context is

5728

@error{} >>> <<<

5751

@error{} $0 ~ "[ >>> \t\n]" <<<

5729

5752

@end example

5730

5753

5731

5754

@cindex newlines, in regexp constants

5754

5777

@cindex regular expressions, dynamic, with embedded newlines

5755

5778

@cindex newlines, in dynamic regexps

5756

5779

5757

Some versions of @command{awk} do not allow the newline

5780

Some older versions of @command{awk} do not allow the newline

5758

5781

character to be used inside a bracket expression for a dynamic regexp:

5759

5782

5760

5783

@example

5763

5786

@error{} ]...

5764

5787

@error{} source line number 1

5765

5788

@error{} context is

5766

@error{} >>> <<<

5789

@error{} $0 ~ "[ >>> \t\n]" <<<

5767

5790

@end example

5768

5791

5769

5792

@cindex newlines, in regexp constants

6087

6110

certain groups of characters in a locale-independent fashion.

6088

6111

6089

6112

@item

6090

@command{gawk}'s @code{IGNORECASE} variable lets you control the

6091

case sensitivity of regexp matching. In other @command{awk}

6092

versions, use @code{tolower()} or @code{toupper()}.

6093

6094

@item

6095

6113

Regular expressions match the leftmost longest text in the string being

6096

6114

matched. This matters for cases where you need to know the extent of

6097

6115

the match, such as for text substitution and when the record separator

6101

6119

Matching expressions may use dynamic regexps, that is, string values

6102

6120

treated as regular expressions.

6103

6121

6122

@item

6123

@command{gawk}'s @code{IGNORECASE} variable lets you control the

6124

case sensitivity of regexp matching. In other @command{awk}

6125

versions, use @code{tolower()} or @code{toupper()}.

6126

6104

6127

@end itemize

6105

6128

6106

6129

@c ENDOFRANGE regexp

6168

6191

@command{awk} divides the input for your program into records and fields.

6169

6192

It keeps track of the number of records that have been read so far from

6170

6193

the current input file. This value is stored in a built-in variable

6171

called @code{FNR} which is reset to zero when a new file is started.

6194

called @code{FNR} which is reset to zero every time a new file is started.

6172

6195

Another built-in variable, @code{NR}, records the total number of input

6173

6196

records read so far from all @value{DF}s. It starts at zero, but is

6174

6197

never automatically reset to zero.

6298

6321

produce correct behavior in the majority of cases, but there

6299

6322

are no guarantees. The moral is: Know Your Data.

6300

6323

6301

There is one unusual case, that occurs when @command{gawk} is

6324

When using regular characters as the record separator,

6325

there is one unusual case that occurs when @command{gawk} is

6302

6326

being fully POSIX-compliant (@pxref{Options}).

6303

6327

Then, the following (extreme) pipeline prints a surprising @samp{1}:

6304

6328

6387

6411

6388

6412

@noindent

6389

6413

The square brackets delineate the contents of @code{RT}, letting you

6390

see the leading and trailing whitespace. The final value of @code{RT}

6414

see the leading and trailing whitespace. The final value of

6391

6415

@code{RT} is a newline.

6392

6416

@xref{Simple Sed}, for a more useful example

6393

6417

of @code{RS} as a regexp and @code{RT}.

6406

6430

the beginning and end of a @emph{line}. As a result, something like

6407

6431

@samp{RS = "^[[:upper:]]"} can only match at the beginning of a file.

6408

6432

This is because @command{gawk} views the input file as one long string

6409

that happens to contain newline characters in it.

6433

that happens to contain newline characters.

6410

6434

It is thus best to avoid anchor characters in the value of @code{RS}.

6411

6435

@end quotation

6412

6436

6416

6440

compatibility mode

6417

6441

(@pxref{Options}).

6418

6442

In compatibility mode, only the first character of the value of

6419

@code{RS} is used to determine the end of the record.

6443

@code{RS} determines the end of the record.

6420

6444

6421

6445

@cindex sidebar, @code{RS = "\0"} Is Not Portable

6422

6446

@ifdocbook

6457

6481

It happens that recent versions of @command{mawk} can use the @value{NUL}

6458

6482

character as a record separator. However, this is a special case:

6459

6483

@command{mawk} does not allow embedded @value{NUL} characters in strings.

6484

(This may change in a future version of @command{mawk}.)

6460

6485

6461

6486

@cindex records, treating files as

6462

6487

@cindex treating files, as single records

6463

@xref{Readfile Function}, for an interesting, portable way to read

6488

@xref{Readfile Function}, for an interesting way to read

6464

6489

whole files. If you are using @command{gawk}, see @ref{Extension Sample

6465

6490

Readfile}, for another option.

6466

6491

6507

6532

It happens that recent versions of @command{mawk} can use the @value{NUL}

6508

6533

character as a record separator. However, this is a special case:

6509

6534

@command{mawk} does not allow embedded @value{NUL} characters in strings.

6535

(This may change in a future version of @command{mawk}.)

6510

6536

6511

6537

@cindex records, treating files as

6512

6538

@cindex treating files, as single records

6513

@xref{Readfile Function}, for an interesting, portable way to read

6539

@xref{Readfile Function}, for an interesting way to read

6514

6540

whole files. If you are using @command{gawk}, see @ref{Extension Sample

6515

6541

Readfile}, for another option.

6516

6542

@end cartouche

6592

6618

6593

6619

@noindent

6594

6620

This example prints each record in the file @file{mail-list} whose first

6595

field contains the string @samp{li}. The operator @samp{~} is called a

6596

@dfn{matching operator}

6597

(@pxref{Regexp Usage});

6598

it tests whether a string (here, the field @code{$1}) matches a given regular

6599

expression.

6621

field contains the string @samp{li}.

6600

6622

6601

By contrast, the following example

6602

looks for @samp{li} in @emph{the entire record} and prints the first

6603

field and the last field for each matching input record:

6623

By contrast, the following example looks for @samp{li} in @emph{the

6624

entire record} and prints the first and last fields for each matching

6625

input record:

6604

6626

6605

6627

@example

6606

6628

$ @kbd{awk '/li/ @{ print $1, $NF @}' mail-list}

6723

6745

of range. For example:

6724

6746

6725

6747

@example

6726

$ awk '@{ $6 = ($5 + $4 + $3 + $2)

6727

> print $6 @}' inventory-shipped

6748

$ @kbd{awk '@{ $6 = ($5 + $4 + $3 + $2)}

6749

> @kbd{ print $6 @}' inventory-shipped}

6728

6750

@print{} 168

6729

6751

@print{} 297

6730

6752

@print{} 301

6813

6835

6814

6836

@example

6815

6837

$ echo a b c d e f | awk '@{ print "NF =", NF;

6816

> NF = 3; print $0 @}'

6838

> NF = 3; print $0 @}'

6817

6839

@print{} NF = 6

6818

6840

@print{} a b c

6819

6841

@end example

6821

6843

@cindex portability, @code{NF} variable@comma{} decrementing

6822

6844

@quotation CAUTION

6823

6845

Some versions of @command{awk} don't

6824

rebuild @code{$0} when @code{NF} is decremented. Caveat emptor.

6846

rebuild @code{$0} when @code{NF} is decremented.

6825

6847

@end quotation

6826

6848

6827

6849

Finally, there are times when it is convenient to force

6857

6879

any leading or trailing whitespace, and the exact whitespace (or other

6858

6880

characters) that separate the fields.

6859

6881

6860

It is a not-uncommon error to try to change the field separators

6882

It is a common error to try to change the field separators

6861

6883

in a record simply by setting @code{FS} and @code{OFS}, and then

6862

6884

expecting a plain @samp{print} or @samp{print $0} to print the

6863

6885

modified record.

6882

6904

any leading or trailing whitespace, and the exact whitespace (or other

6883

6905

characters) that separate the fields.

6884

6906

6885

It is a not-uncommon error to try to change the field separators

6907

It is a common error to try to change the field separators

6886

6908

in a record simply by setting @code{FS} and @code{OFS}, and then

6887

6909

expecting a plain @samp{print} or @samp{print $0} to print the

6888

6910

modified record.

7086

7108

The first @code{print} statement prints the record as it was read,

7087

7109

with leading whitespace intact. The assignment to @code{$2} rebuilds

7088

7110

@code{$0} by concatenating @code{$1} through @code{$NF} together,

7089

separated by the value of @code{OFS}. Because the leading whitespace

7090

was ignored when finding @code{$1}, it is not part of the new @code{$0}.

7091

Finally, the last @code{print} statement prints the new @code{$0}.

7111

separated by the value of @code{OFS} (which is a space by default).

7112

Because the leading whitespace was ignored when finding @code{$1},

7113

it is not part of the new @code{$0}. Finally, the last @code{print}

7114

statement prints the new @code{$0}.

7092

7115

7093

7116

@cindex @code{FS}, containing @code{^}

7094

7117

@cindex @code{^} (caret), in @code{FS}

7110

7133

@example

7111

7134

$ @kbd{echo 'xxAA xxBxx C' |}

7112

7135

> @kbd{gawk -F '(^x+)|( +)' '@{ for (i = 1; i <= NF; i++)}

7113

> @kbd{printf "-->%s<--\n", $i @}'}

7136

> @kbd{ printf "-->%s<--\n", $i @}'}

7114

7137

@print{} --><--

7115

7138

@print{} -->AA<--

7116

7139

@print{} -->xxBxx<--

7173

7196

@noindent

7174

7197

sets @code{FS} to the @samp{,} character. Notice that the option uses

7175

7198

an uppercase @samp{F} instead of a lowercase @samp{f}. The latter

7176

option (@option{-f}) specifies a file

7177

containing an @command{awk} program. Case is significant in command-line

7178

options:

7179

the @option{-F} and @option{-f} options have nothing to do with each other.

7180

You can use both options at the same time to set the @code{FS} variable

7181

@emph{and} get an @command{awk} program from a file.

7199

option (@option{-f}) specifies a file containing an @command{awk} program.

7182

7200

7183

7201

The value used for the argument to @option{-F} is processed in exactly the

7184

7202

same way as assignments to the built-in variable @code{FS}.

7292

7310

If instead you want fields to be separated by a literal period followed

7293

7311

by any single character, use @samp{FS = "\\.."}.

7294

7312

7295

The following table summarizes how fields are split, based on the value

7313

The following list summarizes how fields are split, based on the value

7296

7314

of @code{FS} (@samp{==} means ``is equal to''):

7297

7315

7298

7316

@table @code

7313

7331

7314

7332

@item FS == ""

7315

7333

Each individual character in the record becomes a separate field.

7316

(This is a @command{gawk} extension; it is not specified by the

7317

POSIX standard.)

7334

(This is a common extension; it is not specified by the POSIX standard.)

7318

7335

@end table

7319

7336

7320

7337

@cindex sidebar, Changing @code{FS} Does Not Affect the Fields

7861

7878

Running the program produces the following output:

7862

7879

7863

7880

@example

7864

$ awk -f addrs.awk addresses

7881

$ @kbd{awk -f addrs.awk addresses}

7865

7882

@print{} Name is: Jane Doe

7866

7883

@print{} Address is: 123 Main Street

7867

7884

@print{} City and State are: Anywhere, SE 12345-6789

7873

7890

@dots{}

7874

7891

@end example

7875

7892

7876

@xref{Labels Program}, for a more realistic

7877

program that deals with address lists.

7878

The following

7879

table

7880

summarizes how records are split, based on the

7881

value of

7893

@xref{Labels Program}, for a more realistic program that deals with

7894

address lists. The following list summarizes how records are split,

7895

based on the value of

7882

7896

@ifinfo

7883

7897

@code{RS}.

7884

7898

(@samp{==} means ``is equal to.'')

7913

7927

7914

7928

@cindex @command{gawk}, @code{RT} variable in

7915

7929

@cindex @code{RT} variable

7916

In all cases, @command{gawk} sets @code{RT} to the input text that matched the

7917

value specified by @code{RS}.

7930

If not in compatibility mode (@pxref{Options}), @command{gawk} sets

7931

@code{RT} to the input text that matched the value specified by @code{RS}.

7918

7932

But if the input file ended without any text that matches @code{RS},

7919

7933

then @command{gawk} sets @code{RT} to the null string.

7920

7934

@c ENDOFRANGE recm

8012

8026

while (j == 0) @{

8013

8027

# get more text

8014

8028

if (getline <= 0) @{

8015

m = "unexpected EOF or error"

8016

m = (m ": " ERRNO)

8017

print m > "/dev/stderr"

8029

print("unexpected EOF or error:", ERRNO) > "/dev/stderr"

8018

8030

exit

8019

8031

@}

8020

8032

# build up the line using string concatenation

8283

8295

@end example

8284

8296

8285

8297

@noindent

8286

Notice that this program ran the command @command{who} and printed the previous result.

8298

Notice that this program ran the command @command{who} and printed the result.

8287

8299

(If you try this program yourself, you will of course get different results,

8288

8300

depending upon who is logged in on your system.)

8289

8301

8308

8320

of a construct like @samp{@w{"echo "} "date" | getline}.

8309

8321

Most versions, including the current version, treat it at as

8310

8322

@samp{@w{("echo "} "date") | getline}.

8311

(This how BWK @command{awk} behaves.)

8323

(This is also how BWK @command{awk} behaves.)

8312

8324

Some versions changed and treated it as

8313

8325

@samp{@w{"echo "} ("date" | getline)}.

8314

8326

(This is how @command{mawk} behaves.)

8336

8348

@end example

8337

8349

8338

8350

In this version of @code{getline}, none of the built-in variables are

8339

changed and the record is not split into fields.

8351

changed and the record is not split into fields. However, @code{RT} is set.

8340

8352

8341

8353

@ifinfo

8342

8354

@c Thanks to Paul Eggert for initial wording here

8444

8456

@code{FILENAME} does not have a value inside @code{BEGIN} rules, because you

8445

8457

have not yet started to process the command-line @value{DF}s.

8446

8458

@value{DARKCORNER}

8447

(@xref{BEGIN/END},

8459

(See @ref{BEGIN/END};

8448

8460

also @pxref{Auto-set}.)

8449

8461

8450

8462

@item

8491

8503

@command{gawk} treats @code{getline} like a function call, and evaluates

8492

8504

the expression @samp{a[++c]} before attempting to read from @file{f}.

8493

8505

However, some versions of @command{awk} only evaluate the expression once they

8494

know that there is a string value to be assigned. Caveat Emptor.

8506

know that there is a string value to be assigned.

8495

8507

@end itemize

8496

8508

8497

8509

@node Getline Summary

8507

8519

@float Table,table-getline-variants

8508

8520

@caption{@code{getline} Variants and What They Set}

8509

8521

@multitable @columnfractions .33 .38 .27

8510

@headitem Variant @tab Effect @tab Standard / Extension

8511

@item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, @code{NR}, and @code{RT} @tab Standard

8512

@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR}, @code{NR}, and @code{RT} @tab Standard

8513

@item @code{getline <} @var{file} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Standard

8514

@item @code{getline @var{var} < @var{file}} @tab Sets @var{var} and @code{RT} @tab Standard

8515

@item @var{command} @code{| getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Standard

8516

@item @var{command} @code{| getline} @var{var} @tab Sets @var{var} and @code{RT} @tab Standard

8517

@item @var{command} @code{|& getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab Extension

8518

@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var} and @code{RT} @tab Extension

8522

@headitem Variant @tab Effect @tab @command{awk} / @command{gawk}

8523

@item @code{getline} @tab Sets @code{$0}, @code{NF}, @code{FNR}, @code{NR}, and @code{RT} @tab @command{awk}

8524

@item @code{getline} @var{var} @tab Sets @var{var}, @code{FNR}, @code{NR}, and @code{RT} @tab @command{awk}

8525

@item @code{getline <} @var{file} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{awk}

8526

@item @code{getline @var{var} < @var{file}} @tab Sets @var{var} and @code{RT} @tab @command{awk}

8527

@item @var{command} @code{| getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{awk}

8528

@item @var{command} @code{| getline} @var{var} @tab Sets @var{var} and @code{RT} @tab @command{awk}

8529

@item @var{command} @code{|& getline} @tab Sets @code{$0}, @code{NF}, and @code{RT} @tab @command{gawk}

8530

@item @var{command} @code{|& getline} @var{var} @tab Sets @var{var} and @code{RT} @tab @command{gawk}

8519

8531

@end multitable

8520

8532

@end float

8521

8533

@c ENDOFRANGE getl

8532

8544

You may specify a timeout in milliseconds for reading input from the keyboard,

8533

8545

a pipe, or two-way communication, including TCP/IP sockets. This can be done

8534

8546

on a per input, command or connection basis, by setting a special element

8535

in the @code{PROCINFO} (@pxref{Auto-set}) array:

8547

in the @code{PROCINFO} array (@pxref{Auto-set}):

8536

8548

8537

8549

@example

8538

8550

PROCINFO["input_name", "READ_TIMEOUT"] = @var{timeout in milliseconds}

8564

8576

8565

8577

@command{gawk} terminates the read operation if input does not

8566

8578

arrive after waiting for the timeout period, returns failure

8567

and sets the @code{ERRNO} variable to an appropriate string value.

8579

and sets @code{ERRNO} to an appropriate string value.

8568

8580

A negative or zero value for the timeout is the same as specifying

8569

8581

no timeout at all.

8570

8582

8671

8683

@end multitable

8672

8684

8673

8685

@item

8686

@code{FNR} indicates how many records have been read from the current input file;

8687

@code{NR} indicates how many records have been read in total.

8688

8689

@item

8674

8690

@command{gawk} sets @code{RT} to the text matched by @code{RS}.

8675

8691

8676

8692

@item

8681

8697

characters.

8682

8698

8683

8699

@item

8684

Fields may be referenced using a variable, as in @samp{$NF}. Fields

8700

Fields may be referenced using a variable, as in @code{$NF}. Fields

8685

8701

may also be assigned values, which causes the value of @code{$0} to be

8686

8702

recomputed when it is later referenced. Assigning to a field with a number

8687

8703

greater than @code{NF} creates the field and rebuilds the record, using

8691

8707

@item

8692

8708

Field splitting is more complicated than record splitting.

8693

8709

8694

@multitable @columnfractions .40 .40 .20

8710

@multitable @columnfractions .40 .45 .15

8695

8711

@headitem Field separator value @tab Fields are split @dots{} @tab @command{awk} / @command{gawk}

8696

8712

@item @code{FS == " "} @tab On runs of whitespace @tab @command{awk}

8697

8713

@item @code{FS == @var{any single character}} @tab On that character @tab @command{awk}

8698

8714

@item @code{FS == @var{regexp}} @tab On text matching the regexp @tab @command{awk}

8699

8715

@item @code{FS == ""} @tab Each individual character is a separate field @tab @command{gawk}

8700

8716

@item @code{FIELDWIDTHS == @var{list of columns}} @tab Based on character position @tab @command{gawk}

8701

@item @code{FPAT == @var{regexp}} @tab On text around text matching the regexp @tab @command{gawk}

8717

@item @code{FPAT == @var{regexp}} @tab On the text surrounding text matching the regexp @tab @command{gawk}

8702

8718

@end multitable

8703

8719

8720

@item

8704

8721

Using @samp{FS = "\n"} causes the entire record to be a single field

8705

8722

(assuming that newlines separate records).

8706

8723

8709

8726

This can also be done using command-line variable assignment.

8710

8727

8711

8728

@item

8712

@code{PROCINFO["FS"]} can be used to see how fields are being split.

8729

Use @code{PROCINFO["FS"]} to see how fields are being split.

8713

8730

8714

8731

@item

8715

8732

Use @code{getline} in its various forms to read additional records,

8716

from the default input stream, from a file, or from a pipe or co-process.

8733

from the default input stream, from a file, or from a pipe or coprocess.

8717

8734

8718

8735

@item

8719

8736

Use @code{PROCINFO[@var{file}, "READ_TIMEOUT"]} to cause reads to timeout

8782

8799

* Printf:: The @code{printf} statement.

8783

8800

* Redirection:: How to redirect output to multiple files and

8784

8801

pipes.

8802

* Special FD:: Special files for I/O.

8785

8803

* Special Files:: File name interpretation in @command{gawk}.

8786

8804

@command{gawk} allows access to inherited file

8787

8805

descriptors.

8793

8811

@node Print

8794

8812

@section The @code{print} Statement

8795

8813

8796

The @code{print} statement is used for producing output with simple, standardized

8814

Use the @code{print} statement to produce output with simple, standardized

8797

8815

formatting. You specify only the strings or numbers to print, in a

8798

8816

list separated by commas. They are output, separated by single spaces,

8799

8817

followed by a newline. The statement looks like this:

8817

8835

@cindex text, printing

8818

8836

The simple statement @samp{print} with no items is equivalent to

8819

8837

@samp{print $0}: it prints the entire current record. To print a blank

8820

line, use @samp{print ""}, where @code{""} is the empty string.

8838

line, use @samp{print ""}.

8821

8839

To print a fixed piece of text, use a string constant, such as

8822

8840

@w{@code{"Don't Panic"}}, as one item. If you forget to use the

8823

8841

double-quote characters, your text is taken as an @command{awk}

8825

8843

space is printed between any two items.

8826

8844

8827

8845

Note that the @code{print} statement is a statement and not an

8828

expression---you can't use it the pattern part of a pattern-action

8829

statement, for example.

8846

expression---you can't use it in the pattern part of a

8847

@var{pattern}-@var{action} statement, for example.

8830

8848

8831

8849

@node Print Examples

8832

8850

@section @code{print} Statement Examples

8837

8855

single @code{print} statement can make any number of lines this way.

8838

8856

8839

8857

@cindex newlines, printing

8840

The following is an example of printing a string that contains embedded newlines

8841

(the @samp{\n} is an escape sequence, used to represent the newline

8842

character; @pxref{Escape Sequences}):

8858

The following is an example of printing a string that contains embedded

8859

@ifinfo

8860

newlines

8861

(the @samp{\n} is an escape sequence, used to represent the newline

8862

character; @pxref{Escape Sequences}):

8863

@end ifinfo

8864

@ifhtml

8865

newlines

8866

(the @samp{\n} is an escape sequence, used to represent the newline

8867

character; @pxref{Escape Sequences}):

8868

@end ifhtml

8869

@ifnotinfo

8870

@ifnothtml

8871

newlines:

8872

@end ifnothtml

8873

@end ifnotinfo

8843

8874

8844

8875

@example

8845

8876

$ @kbd{awk 'BEGIN @{ print "line one\nline two\nline three" @}'}

9019

9050

@cindexawkfunc{sprintf}

9020

9051

@cindex @code{OFMT} variable

9021

9052

@cindex output, format specifier@comma{} @code{OFMT}

9022

The built-in variable @code{OFMT} contains the default format specification

9053

The built-in variable @code{OFMT} contains the format specification

9023

9054

that @code{print} uses with @code{sprintf()} when it wants to convert a

9024

9055

number to a string for printing.

9025

9056

The default value of @code{OFMT} is @code{"%.6g"}.

9026

9057

The way @code{print} prints numbers can be changed

9027

by supplying different format specifications

9028

as the value of @code{OFMT}, as shown in the following example:

9058

by supplying a different format specification

9059

for the value of @code{OFMT}, as shown in the following example:

9029

9060

9030

9061

@example

9031

9062

$ @kbd{awk 'BEGIN @{}

9055

9086

specify the width to use for each item, as well as various

9056

9087

formatting choices for numbers (such as what output base to use, whether to

9057

9088

print an exponent, whether to print a sign, and how many digits to print

9058

after the decimal point). You do this by supplying a string, called

9059

the @dfn{format string}, that controls how and where to print the other

9060

arguments.

9089

after the decimal point).

9061

9090

9062

9091

@menu

9063

9092

* Basic Printf:: Syntax of the @code{printf} statement.

9077

9106

@end example

9078

9107

9079

9108

@noindent

9080

The entire list of arguments may optionally be enclosed in parentheses. The

9081

parentheses are necessary if any of the item expressions use the @samp{>}

9082

relational operator; otherwise, it can be confused with an output redirection

9083

(@pxref{Redirection}).

9109

As print @code{print}, the entire list of arguments may optionally be

9110

enclosed in parentheses. Here too, the parentheses are necessary if any

9111

of the item expressions use the @samp{>} relational operator; otherwise,

9112

it can be confused with an output redirection (@pxref{Redirection}).

9084

9113

9085

9114

@cindex format specifiers

9086

9115

The difference between @code{printf} and @code{print} is the @var{format}

9103

9132

@example

9104

9133

$ @kbd{awk 'BEGIN @{}

9105

9134

> @kbd{ORS = "\nOUCH!\n"; OFS = "+"}

9106

> @kbd{msg = "Dont Panic!"}

9135

> @kbd{msg = "Don\47t Panic!"}

9107

9136

> @kbd{printf "%s\n", msg}

9108

9137

> @kbd{@}'}

9109

@print{} Dont Panic!

9138

@print{} Don't Panic!

9110

9139

@end example

9111

9140

9112

9141

@noindent

9128

9157

@c @asis for docbook to come out right

9129

9158

@table @asis

9130

9159

@item @code{%c}

9131

Print a number as an ASCII character; thus, @samp{printf "%c",

9160

Print a number as a character; thus, @samp{printf "%c",

9132

9161

65} outputs the letter @samp{A}. The output for a string value is

9133

9162

the first character of the string.

9134

9163

9154

9183

@item @code{%d}, @code{%i}

9155

9184

Print a decimal integer.

9156

9185

The two control letters are equivalent.

9157

(The @samp{%i} specification is for compatibility with ISO C.)

9186

(The @code{%i} specification is for compatibility with ISO C.)

9158

9187

9159

9188

@item @code{%e}, @code{%E}

9160

9189

Print a number in scientific (exponential) notation;

9169

9198

which follow the decimal point.

9170

9199

(The @samp{4.3} represents two modifiers,

9171

9200

discussed in the next @value{SUBSECTION}.)

9172

@samp{%E} uses @samp{E} instead of @samp{e} in the output.

9201

@code{%E} uses @samp{E} instead of @samp{e} in the output.

9173

9202

9174

9203

@item @code{%f}

9175

9204

Print a number in floating-point notation.

9195

9224

(@pxref{Math Definitions}).

9196

9225

9197

9226

@item @code{%F}

9198

Like @samp{%f} but the infinity and ``not a number'' values are spelled

9227

Like @code{%f} but the infinity and ``not a number'' values are spelled

9199

9228

using uppercase letters.

9200

9229

9201

The @samp{%F} format is a POSIX extension to ISO C; not all systems

9202

support it. On those that don't, @command{gawk} uses @samp{%f} instead.

9230

The @code{%F} format is a POSIX extension to ISO C; not all systems

9231

support it. On those that don't, @command{gawk} uses @code{%f} instead.

9203

9232

9204

9233

@item @code{%g}, @code{%G}

9205

9234

Print a number in either scientific notation or in floating-point

9206

9235

notation, whichever uses fewer characters; if the result is printed in

9207

scientific notation, @samp{%G} uses @samp{E} instead of @samp{e}.

9236

scientific notation, @code{%G} uses @samp{E} instead of @samp{e}.

9208

9237

9209

9238

@item @code{%o}

9210

9239

Print an unsigned octal integer

9220

9249

9221

9250

@item @code{%x}, @code{%X}

9222

9251

Print an unsigned hexadecimal integer;

9223

@samp{%X} uses the letters @samp{A} through @samp{F}

9252

@code{%X} uses the letters @samp{A} through @samp{F}

9224

9253

instead of @samp{a} through @samp{f}

9225

9254

(@pxref{Nondecimal-numbers}).

9226

9255

9235

9264

@quotation NOTE

9236

9265

When using the integer format-control letters for values that are

9237

9266

outside the range of the widest C integer type, @command{gawk} switches to

9238

the @samp{%g} format specifier. If @option{--lint} is provided on the

9267

the @code{%g} format specifier. If @option{--lint} is provided on the

9239

9268

command line (@pxref{Options}), @command{gawk}

9240

9269

warns about this. Other versions of @command{awk} may print invalid

9241

9270

values or do something else entirely.

9251

9280

A format specification can also include @dfn{modifiers} that can control

9252

9281

how much of the item's value is printed, as well as how much space it gets.

9253

9282

The modifiers come between the @samp{%} and the format-control letter.

9254

We will use the bullet symbol ``@bullet{}'' in the following examples to

9283

We use the bullet symbol ``@bullet{}'' in the following examples to

9255

9284

represent

9256

9285

spaces in the output. Here are the possible modifiers, in the order in

9257

9286

which they may appear:

9282

9311

messages at runtime.

9283

9312

@xref{Printf Ordering},

9284

9313

which describes how and why to use positional specifiers.

9285

For now, we will not use them.

9314

For now, we ignore them.

9286

9315

9287

9316

@item -

9288

9317

The minus sign, used before the width modifier (see later on in

9310

9339

9311

9340

@item #

9312

9341

Use an ``alternate form'' for certain control letters.

9313

For @samp{%o}, supply a leading zero.

9314

For @samp{%x} and @samp{%X}, supply a leading @samp{0x} or @samp{0X} for

9342

For @code{%o}, supply a leading zero.

9343

For @code{%x} and @code{%X}, supply a leading @code{0x} or @samp{0X} for

9315

9344

a nonzero result.

9316

For @samp{%e}, @samp{%E}, @samp{%f}, and @samp{%F}, the result always

9345

For @code{%e}, @code{%E}, @code{%f}, and @code{%F}, the result always

9317

9346

contains a decimal point.

9318

For @samp{%g} and @samp{%G}, trailing zeros are not removed from the result.

9347

For @code{%g} and @code{%G}, trailing zeros are not removed from the result.

9319

9348

9320

9349

@item 0

9321

A leading @samp{0} (zero) acts as a flag that indicates that output should be

9350

A leading @samp{0} (zero) acts as a flag indicating that output should be

9322

9351

padded with zeros instead of spaces.

9323

9352

This applies only to the numeric output formats.

9324

9353

This flag only has an effect when the field width is wider than the

9504

9533

@example

9505

9534

awk 'BEGIN @{ print "Name Number"

9506

9535

print "---- ------" @}

9507

@{ printf "%-10s %s\n", $1, $2 @}' mail-list

9536

@{ printf "%-10s %s\n", $1, $2 @}' mail-list

9508

9537

@end example

9509

9538

9510

9539

The above example mixes @code{print} and @code{printf} statements in

9514

9543

@example

9515

9544

awk 'BEGIN @{ printf "%-10s %s\n", "Name", "Number"

9516

9545

printf "%-10s %s\n", "----", "------" @}

9517

@{ printf "%-10s %s\n", $1, $2 @}' mail-list

9546

@{ printf "%-10s %s\n", $1, $2 @}' mail-list

9518

9547

@end example

9519

9548

9520

9549

@noindent

9529

9558

awk 'BEGIN @{ format = "%-10s %s\n"

9530

9559

printf format, "Name", "Number"

9531

9560

printf format, "----", "------" @}

9532

@{ printf format, $1, $2 @}' mail-list

9561

@{ printf format, $1, $2 @}' mail-list

9533

9562

@end example

9534

9563

9535

9564

@c ENDOFRANGE printfs

9550

9579

9551

9580

@quotation NOTE

9552

9581

When @option{--sandbox} is specified (@pxref{Options}),

9553

redirecting output to files and pipes is disabled.

9582

redirecting output to files, pipes and coprocesses is disabled.

9554

9583

@end quotation

9555

9584

9556

9585

A redirection appears after the @code{print} or @code{printf} statement.

9647

9676

9648

9677

@example

9649

9678

report = "mail bug-system"

9650

print "Awk script failed:", $0 | report

9651

m = ("at record number " FNR " of " FILENAME)

9652

print m | report

9679

print("Awk script failed:", $0) | report

9680

print("at record number", FNR, "of", FILENAME) | report

9653

9681

close(report)

9654

9682

@end example

9655

9683

9656

The message is built using string concatenation and saved in the variable

9657

@code{m}. It's then sent down the pipeline to the @command{mail} program.

9658

(The parentheses group the items to concatenate---see

9659

@ref{Concatenation}.)

9660

9661

9684

The @code{close()} function is called here because it's a good idea to close

9662

9685

the pipe as soon as all the intended output has been sent to it.

9663

9686

@xref{Close Files And Pipes},

9800

9823

@c ENDOFRANGE outre

9801

9824

@c ENDOFRANGE reout

9802

9825

9803

@node Special Files

9804

@section Special @value{FFN}s in @command{gawk}

9805

@c STARTOFRANGE gfn

9806

@cindex @command{gawk}, file names in

9807

9808

@command{gawk} provides a number of special @value{FN}s that it interprets

9809

internally. These @value{FN}s provide access to standard file descriptors

9810

and TCP/IP networking.

9811

9812

@menu

9813

* Special FD:: Special files for I/O.

9814

* Special Network:: Special files for network communications.

9815

* Special Caveats:: Things to watch out for.

9816

@end menu

9817

9818

9826

@node Special FD

9819

@subsection Special Files for Standard Descriptors

9827

@section Special Files for Standard Pre-Opened Data Streams

9820

9828

@cindex standard input

9821

9829

@cindex input, standard

9822

9830

@cindex standard output

9827

9835

@cindex files, descriptors, See file descriptors

9828

9836

9829

9837

Running programs conventionally have three input and output streams

9830

already available to them for reading and writing. These are known as

9831

the @dfn{standard input}, @dfn{standard output}, and @dfn{standard error

9832

output}. These streams are, by default, connected to your keyboard and screen, but

9838

already available to them for reading and writing. These are known

9839

as the @dfn{standard input}, @dfn{standard output}, and @dfn{standard

9840

error output}. These open streams (and any other open file or pipe)

9841

are often referred to by the technical term @dfn{file descriptors}.

9842

9843

These streams are, by default, connected to your keyboard and screen, but

9833

9844

they are often redirected with the shell, via the @samp{<}, @samp{<<},

9834

9845

@samp{>}, @samp{>>}, @samp{>&}, and @samp{|} operators. Standard error

9835

9846

is typically used for writing error messages; the reason there are two separate

9838

9849

9839

9850

@cindex differences in @command{awk} and @command{gawk}, error messages

9840

9851

@cindex error handling

9841

In other implementations of @command{awk}, the only way to write an error

9852

In traditional implementations of @command{awk}, the only way to write an error

9842

9853

message to standard error in an @command{awk} program is as follows:

9843

9854

9844

9855

@example

9864

9875

``terminal,''@footnote{The ``tty'' in @file{/dev/tty} stands for

9865

9876

``Teletype,'' a serial terminal.} which on modern systems is a keyboard

9866

9877

and screen, not a serial console.)

9867

This usually has the same effect but not always: although the

9878

This generally has the same effect but not always: although the

9868

9879

standard error stream is usually the screen, it can be redirected; when

9869

9880

that happens, writing to the screen is not correct. In fact, if

9870

9881

@command{awk} is run from a background job, it may not have a

9871

9882

terminal at all.

9872

9883

Then opening @file{/dev/tty} fails.

9873

9884

9874

@command{gawk} provides special @value{FN}s for accessing the three standard

9875

streams. @value{COMMONEXT} It also provides syntax for accessing

9876

any other inherited open files. If the @value{FN} matches

9877

one of these special names when @command{gawk} redirects input or output,

9878

then it directly uses the stream that the @value{FN} stands for.

9879

These special @value{FN}s work for all operating systems that @command{gawk}

9885

@command{gawk}, BWK @command{awk} and @command{mawk} provide

9886

special @value{FN}s for accessing the three standard streams.

9887

If the @value{FN} matches one of these special names when @command{gawk}

9888

(or one of the others) redirects input or output, then it directly uses

9889

the descriptor that the @value{FN} stands for. These special

9890

@value{FN}s work for all operating systems that @command{gawk}

9880

9891

has been ported to, not just those that are POSIX-compliant:

9881

9892

9882

9893

@cindex common extensions, @code{/dev/stdin} special file

9898

9909

9899

9910

@item /dev/stderr

9900

9911

The standard error output (file descriptor 2).

9901

9912

@end table

9913

9914

With these facilities,

9915

the proper way to write an error message then becomes:

9916

9917

@example

9918

print "Serious error detected!" > "/dev/stderr"

9919

@end example

9920

9921

@cindex troubleshooting, quotes with file names

9922

Note the use of quotes around the @value{FN}.

9923

Like any other redirection, the value must be a string.

9924

It is a common error to omit the quotes, which leads

9925

to confusing results.

9926

9927

@command{gawk} does not treat these @value{FN}s as special when

9928

in POSIX compatibility mode. However, since BWK @command{awk}

9929

supports them, @command{gawk} does support them even when

9930

invoked with the @option{--traditional} option (@pxref{Options}).

9931

9932

@node Special Files

9933

@section Special @value{FFN}s in @command{gawk}

9934

@c STARTOFRANGE gfn

9935

@cindex @command{gawk}, file names in

9936

9937

Besides access to standard input, stanard output, and standard error,

9938

@command{gawk} provides access to any open file descriptor.

9939

Additionally, there are special @value{FN}s reserved for

9940

TCP/IP networking.

9941

9942

@menu

9943

* Other Inherited Files:: Accessing other open files with

9944

@command{gawk}.

9945

* Special Network:: Special files for network communications.

9946

* Special Caveats:: Things to watch out for.

9947

@end menu

9948

9949

@node Other Inherited Files

9950

@subsection Accessing Other Open Files With @command{gawk}

9951

9952

Besides the @code{/dev/stdin}, @code{/dev/stdout}, and @code{/dev/stderr}

9953

special @value{FN}s mentioned earlier, @command{gawk} provides syntax

9954

for accessing any other inherited open file:

9955

9956

@table @file

9902

9957

@item /dev/fd/@var{N}

9903

9958

The file associated with file descriptor @var{N}. Such a file must

9904

9959

be opened by the program initiating the @command{awk} execution (typically

9907

9962

@end table

9908

9963

9909

9964

The @value{FN}s @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr}

9910

are aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and @file{/dev/fd/2},

9911

respectively. However, they are more self-explanatory.

9912

The proper way to write an error message in a @command{gawk} program

9913

is to use @file{/dev/stderr}, like this:

9914

9915

@example

9916

print "Serious error detected!" > "/dev/stderr"

9917

@end example

9918

9919

@cindex troubleshooting, quotes with file names

9920

Note the use of quotes around the @value{FN}.

9921

Like any other redirection, the value must be a string.

9922

It is a common error to omit the quotes, which leads

9923

to confusing results.

9924

9925

Finally, using the @code{close()} function on a @value{FN} of the

9965

are essentially aliases for @file{/dev/fd/0}, @file{/dev/fd/1}, and

9966

@file{/dev/fd/2}, respectively. However, those names are more self-explanatory.

9967

9968

Note that using @code{close()} on a @value{FN} of the

9926

9969

form @code{"/dev/fd/@var{N}"}, for file descriptor numbers

9927

9970

above two, does actually close the given file descriptor.

9928

9971

9929

The @file{/dev/stdin}, @file{/dev/stdout}, and @file{/dev/stderr}

9930

special files are also recognized internally by several other

9931

versions of @command{awk}.

9932

9933

9972

@node Special Network

9934

9973

@subsection Special Files for Network Communications

9935

9974

@cindex networks, support for

9958

9997

@node Special Caveats

9959

9998

@subsection Special @value{FFN} Caveats

9960

9999

9961

Here is a list of things to bear in mind when using the

10000

Here are some things to bear in mind when using the

9962

10001

special @value{FN}s that @command{gawk} provides:

9963

10002

9964

10003

@itemize @value{BULLET}

9965

10004

@cindex compatibility mode (@command{gawk}), file names

9966

10005

@cindex file names, in compatibility mode

9967

10006

@item

9968

Recognition of these special @value{FN}s is disabled if @command{gawk} is in

9969

compatibility mode (@pxref{Options}).

10007

Recognition of the @value{FN}s for the three standard pre-opened

10008

files is disabled only in POSIX mode.

10009

10010

@item

10011

Recognition of the other special @value{FN}s is disabled if @command{gawk} is in

10012

compatibility mode (either @option{--traditional} or @option{--posix};

10013

@pxref{Options}).

9970

10014

9971

10015

@item

9972

10016

@command{gawk} @emph{always}

10136

10180

Note also that @samp{close(FILENAME)} has no ``magic'' effects on the

10137

10181

implicit loop that reads through the files named on the command line.

10138

10182

It is, more likely, a close of a file that was never opened with a

10139

redirection, so @command{awk} silently does nothing.

10183

redirection, so @command{awk} silently does nothing, except return

10184

a negative value.

10140

10185

10141

10186

@cindex @code{|} (vertical bar), @code{|&} operator (I/O), pipes@comma{} closing

10142

10187

When using the @samp{|&} operator to communicate with a coprocess,

10148

10193

to start the coprocess.

10149

10194

The second argument should be a string, with either of the values

10150

10195

@code{"to"} or @code{"from"}. Case does not matter.

10151

As this is an advanced feature, a more complete discussion is

10196

As this is an advanced feature, discussion is

10152

10197

delayed until

10153

10198

@ref{Two-way I/O},

10154

which discusses it in more detail and gives an example.

10199

which describes it in more detail and gives an example.

10155

10200

10156

10201

@cindex sidebar, Using @code{close()}'s Return Value

10157

10202

@ifdocbook

10285

10330

10286

10331

@item

10287

10332

Output from both @code{print} and @code{printf} may be redirected to

10288

files, pipes, and co-processes.

10333

files, pipes, and coprocesses.

10289

10334

10290

10335

@item

10291

10336

@command{gawk} provides special file names for access to standard input,

10292

10337

output and error, and for network communications.

10293

10338

10294

10339

@item

10295

Use @code{close()} to close open file, pipe and co-process redirections.

10296

For co-processes, it is possible to close only one direction of the

10340

Use @code{close()} to close open file, pipe and coprocess redirections.

10341

For coprocesses, it is possible to close only one direction of the

10297

10342

communications.

10298

10343

10299

10344

@end itemize

10607

10652

@noindent

10608

10653

are exactly equivalent.

10609

10654

One rather bizarre consequence of this rule is that the following

10610

Boolean expression is valid, but does not do what the user probably

10655

Boolean expression is valid, but does not do what its author probably

10611

10656

intended:

10612

10657

10613

10658

@example

10653

10698

the third argument of @code{split()} to be a regexp constant, but some

10654

10699

older implementations do not.

10655

10700

@value{DARKCORNER}

10656

This can lead to confusion when attempting to use regexp constants

10657

as arguments to user-defined functions

10658

(@pxref{User-defined}).

10659

For example:

10701

Because some built-in functions accept regexp constants as arguments,

10702

it can be confusing when attempting to use regexp constants as arguments

10703

to user-defined functions (@pxref{User-defined}). For example:

10660

10704

10661

10705

@example

10662

10706

function mysub(pat, repl, str, global)

10724

10768

@dfn{decrement operators}.

10725

10769

@xref{Assignment Ops}.

10726

10770

In addition, the @code{sub()} and @code{gsub()} functions can

10727

change a variable's value, and the @code{match()}, @code{patsplit()}

10728

and @code{split()} functions can change the contents of their

10771

change a variable's value, and the @code{match()}, @code{split()}

10772

and @code{patsplit()} functions can change the contents of their

10729

10773

array parameters. @xref{String Functions}.

10730

10774

10731

10775

@cindex variables, built-in

10741

10785

The kind of value a variable holds can change over the life of a program.

10742

10786

By default, variables are initialized to the empty string, which

10743

10787

is zero if converted to a number. There is no need to explicitly

10744

``initialize'' a variable in @command{awk},

10788

initialize a variable in @command{awk},

10745

10789

which is what you would do in C and in most other traditional languages.

10746

10790

10747

10791

@node Assignment Options

10978

11022

@noindent

10979

11023

The @code{en_DK.utf-8} locale is for English in Denmark, where the comma acts as

10980

11024

the decimal point separator. In the normal @code{"C"} locale, @command{gawk}

10981

treats @samp{4,321} as @samp{4}, while in the Danish locale, it's treated

11025

treats @samp{4,321} as 4, while in the Danish locale, it's treated

10982

11026

as the full number, 4.321.

10983

11027

10984

11028

Some earlier versions of @command{gawk} fully complied with this aspect

11535

11579

@end example

11536

11580

11537

11581

@command{gawk} does not have this problem; BWK @command{awk}

11538

and @command{mawk} also do not (@pxref{Other Versions}).

11582

and @command{mawk} also do not.

11539

11583

11540

11584

@docbook

11541

11585

</sidebar>

11581

11625

@end example

11582

11626

11583

11627

@command{gawk} does not have this problem; BWK @command{awk}

11584

and @command{mawk} also do not (@pxref{Other Versions}).

11628

and @command{mawk} also do not.

11585

11629

@end cartouche

11586

11630

@end ifnotdocbook

11587

11631

@c ENDOFRANGE exas

11893

11937

@item

11894

11938

Fields, @code{getline} input, @code{FILENAME}, @code{ARGV} elements,

11895

11939

@code{ENVIRON} elements, and the elements of an array created by

11896

@code{patsplit()}, @code{split()} and @code{match()} that are numeric

11940

@code{match()}, @code{split()} and @code{patsplit()} that are numeric

11897

11941

strings have the @var{strnum} attribute. Otherwise, they have

11898

11942

the @var{string} attribute. Uninitialized variables also have the

11899

11943

@var{strnum} attribute.

12048

12092

The following examples print @samp{1} when the comparison between

12049

12093

the two different constants is true, @samp{0} otherwise:

12050

12094

12095

@c 22.9.2014: Tested with mawk and BWK awk, got same results.

12051

12096

@example

12052

$ @kbd{echo ' +3.14' | gawk '@{ print $0 == " +3.14" @}'} @ii{True}

12053

@print{} 1

12054

$ @kbd{echo ' +3.14' | gawk '@{ print $0 == "+3.14" @}'} @ii{False}

12055

@print{} 0

12056

$ @kbd{echo ' +3.14' | gawk '@{ print $0 == "3.14" @}'} @ii{False}

12057

@print{} 0

12058

$ @kbd{echo ' +3.14' | gawk '@{ print $0 == 3.14 @}'} @ii{True}

12059

@print{} 1

12060

$ @kbd{echo ' +3.14' | gawk '@{ print $1 == " +3.14" @}'} @ii{False}

12061

@print{} 0

12062

$ @kbd{echo ' +3.14' | gawk '@{ print $1 == "+3.14" @}'} @ii{True}

12063

@print{} 1

12064

$ @kbd{echo ' +3.14' | gawk '@{ print $1 == "3.14" @}'} @ii{False}

12065

@print{} 0

12066

$ @kbd{echo ' +3.14' | gawk '@{ print $1 == 3.14 @}'} @ii{True}

12097

$ @kbd{echo ' +3.14' | awk '@{ print($0 == " +3.14") @}'} @ii{True}

12098

@print{} 1

12099

$ @kbd{echo ' +3.14' | awk '@{ print($0 == "+3.14") @}'} @ii{False}

12100

@print{} 0

12101

$ @kbd{echo ' +3.14' | awk '@{ print($0 == "3.14") @}'} @ii{False}

12102

@print{} 0

12103

$ @kbd{echo ' +3.14' | awk '@{ print($0 == 3.14) @}'} @ii{True}

12104

@print{} 1

12105

$ @kbd{echo ' +3.14' | awk '@{ print($1 == " +3.14") @}'} @ii{False}

12106

@print{} 0

12107

$ @kbd{echo ' +3.14' | awk '@{ print($1 == "+3.14") @}'} @ii{True}

12108

@print{} 1

12109

$ @kbd{echo ' +3.14' | awk '@{ print($1 == "3.14") @}'} @ii{False}

12110

@print{} 0

12111

$ @kbd{echo ' +3.14' | awk '@{ print($1 == 3.14) @}'} @ii{True}

12067

12112

@print{} 1

12068

12113

@end example

12069

12114

12137

12182

so similar, this kind of error is very difficult to spot when

12138

12183

scanning the source code.

12139

12184

12140

@cindex @command{gawk}, comparison operators and

12141

The following table of expressions illustrates the kind of comparison

12142

@command{gawk} performs, as well as what the result of the comparison is:

12185

The following list of expressions illustrates the kinds of comparisons

12186

@command{awk} performs, as well as what the result of each comparison is:

12143

12187

12144

12188

@table @code

12145

12189

@item 1.5 <= 2.0

12212

12256

12213

12257

@cindex @command{awk}, regexp constants and

12214

12258

@cindex regexp constants

12215

In modern implementations of @command{awk}, a constant regular

12259

A constant regular

12216

12260

expression in slashes by itself is also an expression. The regexp

12217

12261

@code{/@var{regexp}/} is an abbreviation for the following comparison expression:

12218

12262

12232

12276

The POSIX standard says that string comparison is performed based

12233

12277

on the locale's @dfn{collating order}. This is the order in which

12234

12278

characters sort, as defined by the locale (for more discussion,

12235

@pxref{Ranges and Locales}). This order is usually very different

12279

@pxref{Locales}). This order is usually very different

12236

12280

from the results obtained when doing straight character-by-character

12237

12281

comparison.@footnote{Technically, string comparison is supposed

12238

12282

to behave the same way as if the strings are compared with the C

12312

12356

True if at least one of @var{boolean1} or @var{boolean2} is true.

12313

12357

For example, the following statement prints all records in the input

12314

12358

that contain @emph{either} @samp{edu} or

12315

@samp{li} or both:

12359

@samp{li}:

12316

12360

12317

12361

@example

12318

12362

if ($0 ~ /edu/ || $0 ~ /li/) print

12321

12365

The subexpression @var{boolean2} is evaluated only if @var{boolean1}

12322

12366

is false. This can make a difference when @var{boolean2} contains

12323

12367

expressions that have side effects.

12368

(Thus, this test never really distinguishes records that contain both

12369

@samp{edu} and @samp{li}---as soon as @samp{edu} is matched,

12370

the full test succeeds.)

12324

12371

12325

12372

@item ! @var{boolean}

12326

12373

True if @var{boolean} is false. For example,

12330

12377

12331

12378

@example

12332

12379

BEGIN @{ if (! ("HOME" in ENVIRON))

12333

print "no home!" @}

12380

print "no home!" @}

12334

12381

@end example

12335

12382

12336

12383

(The @code{in} operator is described in

12629

12676

@samp{++}; to avoid the problem the expression can be rewritten as

12630

12677

@samp{$($0++)--}.

12631

12678

12632

This table presents @command{awk}'s operators, in order of highest

12679

This list presents @command{awk}'s operators, in order of highest

12633

12680

to lowest precedence:

12634

12681

12635

12682

@c @asis for docbook to come out right

12786

12833

defines a default @code{"C"} locale, which is an environment that is

12787

12834

typical of what many C programmers are used to.

12788

12835

12789

Once upon a time, the locale setting used to affect regexp matching

12790

(@pxref{Ranges and Locales}), but this is no longer true.

12836

Once upon a time, the locale setting used to affect regexp matching,

12837

but this is no longer true (@pxref{Ranges and Locales}).

12791

12838

12792

12839

Locales can affect record splitting. For the normal case of @samp{RS =

12793

12840

"\n"}, the locale is largely irrelevant. For other single-character

12799

12846

Locales can affect how dates and times are formatted (@pxref{Time

12800

12847

Functions}). For example, a common way to abbreviate the date September

12801

12848

4, 2015 in the United States is ``9/4/15.'' In many countries in

12802

Europe, however, it is abbreviated ``4.9.15.'' Thus, the @samp{%x}

12849

Europe, however, it is abbreviated ``4.9.15.'' Thus, the @code{%x}

12803

12850

specification in a @code{"US"} locale might produce @samp{9/4/15},

12804

12851

while in a @code{"EUROPE"} locale, it might produce @samp{4.9.15}.

12805

12852

12841

12888

@item

12842

12889

@command{awk} provides the usual arithmetic operators (addition,

12843

12890

subtraction, multiplication, division, modulus), and unary plus and minus.

12844

It also provides comparison operators, boolean operators, and regexp

12891

It also provides comparison operators, boolean operators, array membership

12892

testing, and regexp

12845

12893

matching operators. String concatenation is accomplished by placing

12846

12894

two expressions next to each other; there is no explicit operator.

12847

12895

The three-operand @samp{?:} operator provides an ``if-else'' test within

12856

12904

@emph{or} non-null. Otherwise, the value is false.

12857

12905

12858

12906

@item

12859

A value's type is set upon each assignment and may change over its

12907

A variable's type is set upon each assignment and may change over its

12860

12908

lifetime. The type determines how it behaves in comparisons (string

12861

12909

or numeric).

12862

12910

12936

12984

(@xref{Expression Patterns}.)

12937

12985

12938

12986

@item @var{begpat}, @var{endpat}

12939

A pair of patterns separated by a comma, specifying a range of records.

12987

A pair of patterns separated by a comma, specifying a @dfn{range} of records.

12940

12988

The range includes both the initial record that matches @var{begpat} and

12941

12989

the final record that matches @var{endpat}.

12942

12990

(@xref{Ranges}.)

13026

13074

@cindex regexp constants, as patterns

13027

13075

@cindex patterns, regexp constants as

13028

13076

A regexp constant as a pattern is also a special case of an expression

13029

pattern. The expression @code{/li/} has the value one if @samp{li}

13030

appears in the current input record. Thus, as a pattern, @code{/li/}

13077

pattern. The expression @samp{/li/} has the value one if @samp{li}

13078

appears in the current input record. Thus, as a pattern, @samp{/li/}

13031

13079

matches any record containing @samp{li}.

13032

13080

13033

13081

@cindex Boolean expressions, as patterns

13209

13257

@example

13210

13258

$ @kbd{awk '}

13211

13259

> @kbd{BEGIN @{ print "Analysis of \"li\"" @}}

13212

> @kbd{/li/ @{ ++n @}}

13260

> @kbd{/li/ @{ ++n @}}

13213

13261

> @kbd{END @{ print "\"li\" appears in", n, "records." @}' mail-list}

13214

13262

@print{} Analysis of "li"

13215

13263

@print{} "li" appears in 4 records.

13289

13337

rule. It contains the number of fields from the last input record.

13290

13338

Most probably due to an oversight, the standard does not say that @code{$0}

13291

13339

is also preserved, although logically one would think that it should be.

13292

In fact, @command{gawk} does preserve the value of @code{$0} for use in

13293

@code{END} rules. Be aware, however, that BWK @command{awk}, and possibly

13294

other implementations, do not.

13340

In fact, all of BWK @command{awk}, @command{mawk}, and @command{gawk}

13341

preserve the value of @code{$0} for use in @code{END} rules. Be aware,

13342

however, that some other implementations and many older versions

13343

of Unix @command{awk} do not.

13295

13344

13296

13345

The third point follows from the first two. The meaning of @samp{print}

13297

13346

inside a @code{BEGIN} or @code{END} rule is the same as always:

13386

13435

13387

13436

@cindex @code{next} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and

13388

13437

The @code{next} statement (@pxref{Next Statement}) is not allowed inside

13389

either a @code{BEGINFILE} or and @code{ENDFILE} rule. The @code{nextfile}

13390

statement (@pxref{Nextfile Statement}) is allowed only inside a

13438

either a @code{BEGINFILE} or an @code{ENDFILE} rule. The @code{nextfile}

13439

statement is allowed only inside a

13391

13440

@code{BEGINFILE} rule, but not inside an @code{ENDFILE} rule.

13392

13441

13393

13442

@cindex @code{getline} statement, @code{BEGINFILE}/@code{ENDFILE} patterns and

13451

13500

into the body of the @command{awk} program.

13452

13501

13453

13502

@cindex shells, quoting

13454

The most common method is to use shell quoting to substitute

13503

A common method is to use shell quoting to substitute

13455

13504

the variable's value into the program inside the script.

13456

13505

For example, consider the following program:

13457

13506

13708

13757

is not zero and not a null string.)

13709

13758

@end ifinfo

13710

13759

After @var{body} has been executed,

13711

@var{condition} is tested again, and if it is still true, @var{body} is

13712

executed again. This process repeats until the @var{condition} is no longer

13713

true. If the @var{condition} is initially false, the body of the loop is

13714

never executed and @command{awk} continues with the statement following

13760

@var{condition} is tested again, and if it is still true, @var{body}

13761

executes again. This process repeats until the @var{condition} is no longer

13762

true. If the @var{condition} is initially false, the body of the loop

13763

never executes and @command{awk} continues with the statement following

13715

13764

the loop.

13716

13765

This example prints the first three fields of each record, one per line:

13717

13766

13718

13767

@example

13719

awk '@{

13720

i = 1

13721

while (i <= 3) @{

13722

print $i

13723

i++

13724

@}

13768

awk '

13769

@{

13770

i = 1

13771

while (i <= 3) @{

13772

print $i

13773

i++

13774

@}

13725

13775

@}' inventory-shipped

13726

13776

@end example

13727

13777

13755

13805

while (@var{condition})

13756

13806

@end example

13757

13807

13758

Even if the @var{condition} is false at the start, the @var{body} is

13759

executed at least once (and only once, unless executing @var{body}

13808

Even if the @var{condition} is false at the start, the @var{body}

13809

executes at least once (and only once, unless executing @var{body}

13760

13810

makes @var{condition} true). Contrast this with the corresponding

13761

13811

@code{while} statement:

13762

13812

13763

13813

@example

13764

13814

while (@var{condition})

13765

@var{body}

13815

@var{body}

13766

13816

@end example

13767

13817

13768

13818

@noindent

13772

13822

13773

13823

@example

13774

13824

@{

13775

i = 1

13776

do @{

13777

print $0

13778

i++

13779

@} while (i <= 10)

13825

i = 1

13826

do @{

13827

print $0

13828

i++

13829

@} while (i <= 10)

13780

13830

@}

13781

13831

@end example

13782

13832

13813

13863

For example:

13814

13864

13815

13865

@example

13816

awk '@{

13817

for (i = 1; i <= 3; i++)

13818

print $i

13866

awk '

13867

@{

13868

for (i = 1; i <= 3; i++)

13869

print $i

13819

13870

@}' inventory-shipped

13820

13871

@end example

13821

13872

13843

13894

13844

13895

@example

13845

13896

for (i = 1; i <= 100; i *= 2)

13846

print i

13897

print i

13847

13898

@end example

13848

13899

13849

13900

If there is nothing to be done, any of the three expressions in the

14163

14214

@cindex functions, user-defined, @code{next}/@code{nextfile} statements and

14164

14215

According to the POSIX standard, the behavior is undefined if the

14165

14216

@code{next} statement is used in a @code{BEGIN} or @code{END} rule.

14166

@command{gawk} treats it as a syntax error. Although POSIX permits it,

14217

@command{gawk} treats it as a syntax error. Although POSIX does not disallow it,

14167

14218

most other @command{awk} implementations don't allow the @code{next}

14168

14219

statement inside function bodies (@pxref{User-defined}). Just as with any

14169

14220

other @code{next} statement, a @code{next} statement inside a function

14218

14269

14219

14270

@quotation NOTE

14220

14271

For many years, @code{nextfile} was a

14221

@command{gawk} extension. As of September, 2012, it was accepted for

14272

common extension. In September, 2012, it was accepted for

14222

14273

inclusion into the POSIX standard.

14223

14274

See @uref{http://austingroupbugs.net/view.php?id=607, the Austin Group website}.

14224

14275

@end quotation

14227

14278

@cindex @code{nextfile} statement, user-defined functions and

14228

14279

@cindex Brian Kernighan's @command{awk}

14229

14280

@cindex @command{mawk} utility

14230

The current version of BWK @command{awk}, and @command{mawk} (@pxref{Other

14231

Versions}) also support @code{nextfile}. However, they don't allow the

14281

The current version of BWK @command{awk}, and @command{mawk}

14282

also support @code{nextfile}. However, they don't allow the

14232

14283

@code{nextfile} statement inside function bodies (@pxref{User-defined}).

14233

14284

@command{gawk} does; a @code{nextfile} inside a function body reads the

14234

14285

next record and starts processing it with the first rule in the program,

14260

14311

An @code{exit} statement that is not part of a @code{BEGIN} or @code{END}

14261

14312

rule stops the execution of any further automatic rules for the current

14262

14313

record, skips reading any remaining input records, and executes the

14263

@code{END} rule if there is one.

14264

Any @code{ENDFILE} rules are also skipped; they are not executed.

14314

@code{END} rule if there is one. @command{gawk} also skips

14315

any @code{ENDFILE} rules; they do not execute.

14265

14316

14266

14317

In such a case,

14267

14318

if you don't want the @code{END} rule to do its job, set a variable

14369

14420

@code{"wr"} indicates that all files should use binary I/O. Any other

14370

14421

string value is treated the same as @code{"rw"}, but causes @command{gawk}

14371

14422

to generate a warning message. @code{BINMODE} is described in more

14372

detail in @ref{PC Using}. @command{mawk} @pxref{Other Versions}),

14423

detail in @ref{PC Using}. @command{mawk} (@pxref{Other Versions}),

14373

14424

also supports this variable, but only using numeric values.

14374

14425

14375

14426

@cindex @code{CONVFMT} variable

14496

14547

as the first argument to the @code{sprintf()} function

14497

14548

(@pxref{String Functions}).

14498

14549

Its default value is @code{"%.6g"}. Earlier versions of @command{awk}

14499

also used @code{OFMT} to specify the format for converting numbers to

14550

used @code{OFMT} to specify the format for converting numbers to

14500

14551

strings in general expressions; this is now done by @code{CONVFMT}.

14501

14552

14502

14553

@cindex @code{sprintf()} function, @code{OFMT} variable and

14648

14699

14649

14700

@cindex file names, distinguishing

14650

14701

While you can change the value of @code{ARGIND} within your @command{awk}

14651

program, @command{gawk} automatically sets it to a new value when the

14652

next file is opened.

14702

program, @command{gawk} automatically sets it to a new value when it

14703

opens the next file.

14653

14704

14654

14705

@cindex @code{ENVIRON} array

14655

14706

@cindex environment variables, in @code{ENVIRON} array

14714

14765

14715

14766

@cindex @code{FNR} variable

14716

14767

@item @code{FNR}

14717

The current record number in the current file. @code{FNR} is

14718

incremented each time a new record is read

14719

(@pxref{Records}). It is reinitialized

14720

to zero each time a new input file is started.

14768

The current record number in the current file. @command{awk} increments

14769

@code{FNR} each time it reads a new record (@pxref{Records}).

14770

@command{awk} resets @code{FNR} to zero each time it starts a new

14771

input file.

14721

14772

14722

14773

@cindex @code{NF} variable

14723

14774

@item @code{NF}

14749

14800

The number of input records @command{awk} has processed since

14750

14801

the beginning of the program's execution

14751

14802

(@pxref{Records}).

14752

@code{NR} is incremented each time a new record is read.

14803

@command{awk} increments @code{NR} each time it reads a new record.

14753

14804

14754

14805

@cindex @command{gawk}, @code{PROCINFO} array in

14755

14806

@cindex @code{PROCINFO} array

14829

14880

@item PROCINFO["sorted_in"]

14830

14881

If this element exists in @code{PROCINFO}, its value controls the

14831

14882

order in which array indices will be processed by

14832

@samp{for (@var{index} in @var{array})} loops.

14883

@samp{for (@var{indx} in @var{array})} loops.

14833

14884

Since this is an advanced feature, we defer the

14834

14885

full description until later; see

14835

14886

@ref{Scanning an Array}.

14850

14901

14851

14902

The following additional elements in the array

14852

14903

are available to provide information about the MPFR and GMP libraries

14853

if your version of @command{gawk} supports arbitrary precision numbers

14904

if your version of @command{gawk} supports arbitrary precision arithmetic

14854

14905

(@pxref{Arbitrary Precision Arithmetic}):

14855

14906

14856

14907

@table @code

14899

14950

14900

14951

@itemize @value{BULLET}

14901

14952

@item

14953

It may be used to provide a timeout when reading from any

14954

open input file, pipe, or coprocess.

14955

@xref{Read Timeout}, for more information.

14956

14957

@item

14902

14958

It may be used to cause coprocesses to communicate over pseudo-ttys

14903

14959

instead of through two-way pipes; this is discussed further in

14904

14960

@ref{Two-way I/O}.

14905

14906

@item

14907

It may be used to provide a timeout when reading from any

14908

open input file, pipe, or coprocess.

14909

@xref{Read Timeout}, for more information.

14910

14961

@end itemize

14911

14962

14912

14963

@cindex @code{RLENGTH} variable

15194

15245

(@xref{Getopt Function}, for an @command{awk} library function that

15195

15246

parses command-line options.)

15196

15247

15248

When designing your program, you should choose options that don't

15249

conflict with @command{gawk}'s, since it will process any options

15250

that it accepts before passing the rest of the command line on to

15251

your program. Using @samp{#!} with the @option{-E} option may help

15252

(@pxref{Executable Scripts}, and @pxref{Options}).

15253

15197

15254

@node Pattern Action Summary

15198

15255

@section Summary

15199

15256

15228

15285

The control statements in @command{awk} are @code{if}-@code{else},

15229

15286

@code{while}, @code{for}, and @code{do}-@code{while}. @command{gawk}

15230

15287

adds the @code{switch} statement. There are two flavors of @code{for}

15231

statement: one for for performing general looping, and the other iterating

15288

statement: one for performing general looping, and the other for iterating

15232

15289

through an array.

15233

15290

15234

15291

@item

15245

15302

from an action (or function body) it transfers control to the

15246

15303

@code{END} statements. From an @code{END} statement body, it exits

15247

15304

immediately. You may pass an optional numeric value to be used

15248

at @command{awk}'s exit status.

15305

as @command{awk}'s exit status.

15249

15306

15250

15307

@item

15251

15308

Some built-in variables provide control over @command{awk}, mainly for I/O.

15252

15309

Other variables convey information from @command{awk} to your program.

15253

15310

15311

@item

15312

@code{ARGC} and @code{ARGV} make the command-line arguments available

15313

to your program. Manipulating them from a @code{BEGIN} rule lets you

15314

control how @command{awk} will process the provided @value{DF}s.

15315

15254

15316

@end itemize

15255

15317

15256

15318

@node Arrays

15271

15333

for sorting arrays, and ends with a brief description of @command{gawk}'s

15272

15334

ability to support true arrays of arrays.

15273

15335

15274

@cindex variables, names of

15275

@cindex functions, names of

15276

@cindex arrays, names of, and names of functions/variables

15277

@cindex names, arrays/variables

15278

@cindex namespace issues

15279

@command{awk} maintains a single set

15280

of names that may be used for naming variables, arrays, and functions

15281

(@pxref{User-defined}).

15282

Thus, you cannot have a variable and an array with the same name in the

15283

same @command{awk} program.

15284

15285

15336

@menu

15286

15337

* Array Basics:: The basics of arrays.

15338

* Numeric Array Subscripts:: How to use numbers as subscripts in

15339

@command{awk}.

15340

* Uninitialized Subscripts:: Using Uninitialized variables as subscripts.

15287

15341

* Delete:: The @code{delete} statement removes an element

15288

15342

from an array.

15289

* Numeric Array Subscripts:: How to use numbers as subscripts in

15290

@command{awk}.

15291

* Uninitialized Subscripts:: Using Uninitialized variables as subscripts.

15292

15343

* Multidimensional:: Emulating multidimensional arrays in

15293

15344

@command{awk}.

15294

15345

* Arrays of Arrays:: True multidimensional arrays.

15716

15767

@example

15717

15768

@c file eg/misc/arraymax.awk

15718

15769

@{

15719

if ($1 > max)

15720

max = $1

15721

arr[$1] = $0

15770

if ($1 > max)

15771

max = $1

15772

arr[$1] = $0

15722

15773

@}

15723

15774

15724

15775

END @{

15725

for (x = 1; x <= max; x++)

15726

print arr[x]

15776

for (x = 1; x <= max; x++)

15777

print arr[x]

15727

15778

@}

15728

15779

@c endfile

15729

15780

@end example

15763

15814

15764

15815

@example

15765

15816

END @{

15766

for (x = 1; x <= max; x++)

15767

if (x in arr)

15768

print arr[x]

15817

for (x = 1; x <= max; x++)

15818

if (x in arr)

15819

print arr[x]

15769

15820

@}

15770

15821

@end example

15771

15822

15787

15838

15788

15839

@example

15789

15840

for (@var{var} in @var{array})

15790

@var{body}

15841

@var{body}

15791

15842

@end example

15792

15843

15793

15844

@noindent

15860

15911

@}

15861

15912

@end example

15862

15913

15863

Here is what happens when run with @command{gawk}:

15914

Here is what happens when run with @command{gawk} (and @command{mawk}):

15864

15915

15865

15916

@example

15866

15917

$ @kbd{gawk -f loopcheck.awk}

15978

16029

For example:

15979

16030

15980

16031

@example

15981

$ @kbd{gawk 'BEGIN @{}

16032

$ @kbd{gawk '}

16033

> @kbd{BEGIN @{}

15982

16034

> @kbd{ a[4] = 4}

15983

16035

> @kbd{ a[3] = 3}

15984

16036

> @kbd{ for (i in a)}

15986

16038

> @kbd{@}'}

15987

16039

@print{} 4 4

15988

16040

@print{} 3 3

15989

$ @kbd{gawk 'BEGIN @{}

16041

$ @kbd{gawk '}

16042

> @kbd{BEGIN @{}

15990

16043

> @kbd{ PROCINFO["sorted_in"] = "@@ind_str_asc"}

15991

16044

> @kbd{ a[4] = 4}

15992

16045

> @kbd{ a[3] = 3}

16035

16088

In addition, @command{gawk} provides built-in functions for

16036

16089

sorting arrays; see @ref{Array Sorting Functions}.

16037

16090

16038

@node Delete

16039

@section The @code{delete} Statement

16040

@cindex @code{delete} statement

16041

@cindex deleting elements in arrays

16042

@cindex arrays, elements, deleting

16043

@cindex elements in arrays, deleting

16044

16045

To remove an individual element of an array, use the @code{delete}

16046

statement:

16047

16048

@example

16049

delete @var{array}[@var{index-expression}]

16050

@end example

16051

16052

Once an array element has been deleted, any value the element once

16053

had is no longer available. It is as if the element had never

16054

been referred to or been given a value.

16055

The following is an example of deleting elements in an array:

16056

16057

@example

16058

for (i in frequencies)

16059

delete frequencies[i]

16060

@end example

16061

16062

@noindent

16063

This example removes all the elements from the array @code{frequencies}.

16064

Once an element is deleted, a subsequent @code{for} statement to scan the array

16065

does not report that element and the @code{in} operator to check for

16066

the presence of that element returns zero (i.e., false):

16067

16068

@example

16069

delete foo[4]

16070

if (4 in foo)

16071

print "This will never be printed"

16072

@end example

16073

16074

@cindex null strings, and deleting array elements

16075

It is important to note that deleting an element is @emph{not} the

16076

same as assigning it a null value (the empty string, @code{""}).

16077

For example:

16078

16079

@example

16080

foo[4] = ""

16081

if (4 in foo)

16082

print "This is printed, even though foo[4] is empty"

16083

@end example

16084

16085

@cindex lint checking, array elements

16086

It is not an error to delete an element that does not exist.

16087

However, if @option{--lint} is provided on the command line

16088

(@pxref{Options}),

16089

@command{gawk} issues a warning message when an element that

16090

is not in the array is deleted.

16091

16092

@cindex common extensions, @code{delete} to delete entire arrays

16093

@cindex extensions, common@comma{} @code{delete} to delete entire arrays

16094

@cindex arrays, deleting entire contents

16095

@cindex deleting entire arrays

16096

@cindex @code{delete} @var{array}

16097

@cindex differences in @command{awk} and @command{gawk}, array elements, deleting

16098

All the elements of an array may be deleted with a single statement

16099

by leaving off the subscript in the @code{delete} statement,

16100

as follows:

16101

16102

16103

@example

16104

delete @var{array}

16105

@end example

16106

16107

Using this version of the @code{delete} statement is about three times

16108

more efficient than the equivalent loop that deletes each element one

16109

at a time.

16110

16111

@cindex Brian Kernighan's @command{awk}

16112

@quotation NOTE

16113

For many years,

16114

using @code{delete} without a subscript was a @command{gawk} extension.

16115

As of September, 2012, it was accepted for

16116

inclusion into the POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544,

16117

the Austin Group website}. This form of the @code{delete} statement is also supported

16118

by BWK @command{awk} and @command{mawk}, as well as

16119

by a number of other implementations (@pxref{Other Versions}).

16120

@end quotation

16121

16122

@cindex portability, deleting array elements

16123

@cindex Brennan, Michael

16124

The following statement provides a portable but nonobvious way to clear

16125

out an array:@footnote{Thanks to Michael Brennan for pointing this out.}

16126

16127

@example

16128

split("", array)

16129

@end example

16130

16131

@cindex @code{split()} function, array elements@comma{} deleting

16132

The @code{split()} function

16133

(@pxref{String Functions})

16134

clears out the target array first. This call asks it to split

16135

apart the null string. Because there is no data to split out, the

16136

function simply clears the array and then returns.

16137

16138

@quotation CAUTION

16139

Deleting an array does not change its type; you cannot

16140

delete an array and then use the array's name as a scalar

16141

(i.e., a regular variable). For example, the following does not work:

16142

16143

@example

16144

a[1] = 3

16145

delete a

16146

a = 3

16147

@end example

16148

@end quotation

16149

16150

16091

@node Numeric Array Subscripts

16151

16092

@section Using Numbers to Subscript Arrays

16152

16093

16187

16128

@cindex integer array indices

16188

16129

According to the rules for conversions

16189

16130

(@pxref{Conversion}), integer

16190

values are always converted to strings as integers, no matter what the

16131

values always convert to strings as integers, no matter what the

16191

16132

value of @code{CONVFMT} may happen to be. So the usual case of

16192

16133

the following works:

16193

16134

16210

16151

all refer to the same element!

16211

16152

16212

16153

As with many things in @command{awk}, the majority of the time

16213

things work as one would expect them to. But it is useful to have a precise

16154

things work as you would expect them to. But it is useful to have a precise

16214

16155

knowledge of the actual rules since they can sometimes have a subtle

16215

16156

effect on your programs.

16216

16157

16274

16215

if @option{--lint} is provided

16275

16216

on the command line (@pxref{Options}).

16276

16217

16218

@node Delete

16219

@section The @code{delete} Statement

16220

@cindex @code{delete} statement

16221

@cindex deleting elements in arrays

16222

@cindex arrays, elements, deleting

16223

@cindex elements in arrays, deleting

16224

16225

To remove an individual element of an array, use the @code{delete}

16226

statement:

16227

16228

@example

16229

delete @var{array}[@var{index-expression}]

16230

@end example

16231

16232

Once an array element has been deleted, any value the element once

16233

had is no longer available. It is as if the element had never

16234

been referred to or been given a value.

16235

The following is an example of deleting elements in an array:

16236

16237

@example

16238

for (i in frequencies)

16239

delete frequencies[i]

16240

@end example

16241

16242

@noindent

16243

This example removes all the elements from the array @code{frequencies}.

16244

Once an element is deleted, a subsequent @code{for} statement to scan the array

16245

does not report that element and the @code{in} operator to check for

16246

the presence of that element returns zero (i.e., false):

16247

16248

@example

16249

delete foo[4]

16250

if (4 in foo)

16251

print "This will never be printed"

16252

@end example

16253

16254

@cindex null strings, and deleting array elements

16255

It is important to note that deleting an element is @emph{not} the

16256

same as assigning it a null value (the empty string, @code{""}).

16257

For example:

16258

16259

@example

16260

foo[4] = ""

16261

if (4 in foo)

16262

print "This is printed, even though foo[4] is empty"

16263

@end example

16264

16265

@cindex lint checking, array elements

16266

It is not an error to delete an element that does not exist.

16267

However, if @option{--lint} is provided on the command line

16268

(@pxref{Options}),

16269

@command{gawk} issues a warning message when an element that

16270

is not in the array is deleted.

16271

16272

@cindex common extensions, @code{delete} to delete entire arrays

16273

@cindex extensions, common@comma{} @code{delete} to delete entire arrays

16274

@cindex arrays, deleting entire contents

16275

@cindex deleting entire arrays

16276

@cindex @code{delete} @var{array}

16277

@cindex differences in @command{awk} and @command{gawk}, array elements, deleting

16278

All the elements of an array may be deleted with a single statement

16279

by leaving off the subscript in the @code{delete} statement,

16280

as follows:

16281

16282

16283

@example

16284

delete @var{array}

16285

@end example

16286

16287

Using this version of the @code{delete} statement is about three times

16288

more efficient than the equivalent loop that deletes each element one

16289

at a time.

16290

16291

This form of the @code{delete} statement is also supported

16292

by BWK @command{awk} and @command{mawk}, as well as

16293

by a number of other implementations.

16294

16295

@cindex Brian Kernighan's @command{awk}

16296

@quotation NOTE

16297

For many years, using @code{delete} without a subscript was a common

16298

extension. In September, 2012, it was accepted for inclusion into the

16299

POSIX standard. See @uref{http://austingroupbugs.net/view.php?id=544,

16300

the Austin Group website}.

16301

@end quotation

16302

16303

@cindex portability, deleting array elements

16304

@cindex Brennan, Michael

16305

The following statement provides a portable but nonobvious way to clear

16306

out an array:@footnote{Thanks to Michael Brennan for pointing this out.}

16307

16308

@example

16309

split("", array)

16310

@end example

16311

16312

@cindex @code{split()} function, array elements@comma{} deleting

16313

The @code{split()} function

16314

(@pxref{String Functions})

16315

clears out the target array first. This call asks it to split

16316

apart the null string. Because there is no data to split out, the

16317

function simply clears the array and then returns.

16318

16319

@quotation CAUTION

16320

Deleting all the elements from an array does not change its type; you cannot

16321

clear an array and then use the array's name as a scalar

16322

(i.e., a regular variable). For example, the following does not work:

16323

16324

@example

16325

a[1] = 3

16326

delete a

16327

a = 3

16328

@end example

16329

@end quotation

16330

16277

16331

@node Multidimensional

16278

16332

@section Multidimensional Arrays

16279

16333

16285

16339

@cindex arrays, multidimensional

16286

16340

A multidimensional array is an array in which an element is identified

16287

16341

by a sequence of indices instead of a single index. For example, a

16288

two-dimensional array requires two indices. The usual way (in most

16342

two-dimensional array requires two indices. The usual way (in many

16289

16343

languages, including @command{awk}) to refer to an element of a

16290

16344

two-dimensional array named @code{grid} is with

16291

16345

@code{grid[@var{x},@var{y}]}.

16460

16514

Each subarray and the main array can be of different length. In fact, the

16461

16515

elements of an array or its subarray do not all have to have the same

16462

16516

type. This means that the main array and any of its subarrays can be

16463

non-rectangular, or jagged in structure. One can assign a scalar value to

16464

the index @code{4} of the main array @code{a}:

16517

non-rectangular, or jagged in structure. You can assign a scalar value to

16518

the index @code{4} of the main array @code{a}, even though @code{a[1]}

16519

is itself an array and not a scalar:

16465

16520

16466

16521

@example

16467

16522

a[4] = "An element in a jagged array"

16543

16598

print array[i][j]

16544

16599

@}

16545

16600

@}

16601

else

16602

print array[i]

16546

16603

@}

16547

16604

@end example

16548

16605

16827

16884

that can be used to obtain a random non-negative integer less than @var{n}:

16828

16885

16829

16886

@example

16830

function randint(n) @{

16831

return int(n * rand())

16887

function randint(n)

16888

@{

16889

return int(n * rand())

16832

16890

@}

16833

16891

@end example

16834

16892

16848

16906

# Roll 3 six-sided dice and

16849

16907

# print total number of points.

16850

16908

@{

16851

printf("%d points\n",

16852

roll(6)+roll(6)+roll(6))

16909

printf("%d points\n", roll(6) + roll(6) + roll(6))

16853

16910

@}

16854

16911

@end example

16855

16912

16938

16995

In the following list, optional parameters are enclosed in square brackets@w{ ([ ]).}

16939

16996

Several functions perform string substitution; the full discussion is

16940

16997

provided in the description of the @code{sub()} function, which comes

16941

towards the end since the list is presented in alphabetic order.

16998

towards the end since the list is presented alphabetically.

16942

16999

16943

17000

Those functions that are specific to @command{gawk} are marked with a

16944

17001

pound sign (@samp{#}). They are not available in compatibility mode

16982

17039

(@pxref{Array Sorting Functions}). If the

16983

17040

@var{source} array contains subarrays as values (@pxref{Arrays of

16984

17041

Arrays}), they will come last, after all scalar values.

17042

Subarrays are @emph{not} recursively sorted.

16985

17043

16986

17044

For example, if the contents of @code{a} are as follows:

16987

17045

17118

17176

@noindent

17119

17177

If @var{find} is not found, @code{index()} returns zero.

17120

17178

17121

It is a fatal error to use a regexp constant for @var{find}.

17179

With BWK @command{awk} and @command{gawk},

17180

it is a fatal error to use a regexp constant for @var{find}.

17181

Other implementations allow it, simply treating the regexp

17182

constant as an expression meaning @samp{$0 ~ /regexp/}.

17122

17183

17123

17184

@item @code{length(}[@var{string}]@code{)}

17124

17185

@cindexawkfunc{length}

17232

17293

@example

17233

17294

@c file eg/misc/findpat.awk

17234

17295

@{

17235

if ($1 == "FIND")

17236

regex = $2

17237

else @{

17238

where = match($0, regex)

17239

if (where != 0)

17240

print "Match of", regex, "found at",

17241

where, "in", $0

17296

if ($1 == "FIND")

17297

regex = $2

17298

else @{

17299

where = match($0, regex)

17300

if (where != 0)

17301

print "Match of", regex, "found at", where, "in", $0

17242

17302

@}

17243

17303

@}

17244

17304

@c endfile

17334

17394

17335

17395

The @code{patsplit()} function splits strings into pieces in a

17336

17396

manner similar to the way input lines are split into fields using @code{FPAT}

17337

(@pxref{Splitting By Content}.

17397

(@pxref{Splitting By Content}).

17338

17398

17339

17399

Before splitting the string, @code{patsplit()} deletes any previously existing

17340

17400

elements in the arrays @var{array} and @var{seps}.

17347

17407

@code{@var{array}[1]}, the second piece in @code{@var{array}[2]}, and so

17348

17408

forth. The string value of the third argument, @var{fieldsep}, is

17349

17409

a regexp describing where to split @var{string} (much as @code{FS} can

17350

be a regexp describing where to split input records;

17351

@pxref{Regexp Field Splitting}).

17410

be a regexp describing where to split input records).

17352

17411

If @var{fieldsep} is omitted, the value of @code{FS} is used.

17353

17412

@code{split()} returns the number of elements created.

17354

17413

@var{seps} is a @command{gawk} extension with @code{@var{seps}[@var{i}]}

17643

17702

@code{toupper("MiXeD cAsE 123")} returns @code{"MIXED CASE 123"}.

17644

17703

@end table

17645

17704

17705

@cindex sidebar, Matching the Null String

17706

@ifdocbook

17707

@docbook

17708

<sidebar><title>Matching the Null String</title>

17709

@end docbook

17710

17711

@cindex matching, null strings

17712

@cindex null strings, matching

17713

@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching

17714

@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching

17715

17716

In @command{awk}, the @samp{*} operator can match the null string.

17717

This is particularly important for the @code{sub()}, @code{gsub()},

17718

and @code{gensub()} functions. For example:

17719

17720

@example

17721

$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'}

17722

@print{} XaXbXcX

17723

@end example

17724

17725

@noindent

17726

Although this makes a certain amount of sense, it can be surprising.

17727

17728

@docbook

17729

</sidebar>

17730

@end docbook

17731

@end ifdocbook

17732

17733

@ifnotdocbook

17734

@cartouche

17735

@center @b{Matching the Null String}

17736

17737

17738

@cindex matching, null strings

17739

@cindex null strings, matching

17740

@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching

17741

@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching

17742

17743

In @command{awk}, the @samp{*} operator can match the null string.

17744

This is particularly important for the @code{sub()}, @code{gsub()},

17745

and @code{gensub()} functions. For example:

17746

17747

@example

17748

$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'}

17749

@print{} XaXbXcX

17750

@end example

17751

17752

@noindent

17753

Although this makes a certain amount of sense, it can be surprising.

17754

@end cartouche

17755

@end ifnotdocbook

17756

17757

17646

17758

@node Gory Details

17647

17759

@subsubsection More About @samp{\} and @samp{&} with @code{sub()}, @code{gsub()}, and @code{gensub()}

17648

17760

17656

17768

@cindex ampersand (@code{&}), @code{gsub()}/@code{gensub()}/@code{sub()} functions and

17657

17769

17658

17770

@quotation CAUTION

17659

This section has been known to cause headaches.

17771

This subsubsection has been reported to cause headaches.

17660

17772

You might want to skip it upon first reading.

17661

17773

@end quotation

17662

17774

17947

18059

we recommend the use of @command{gawk} and @code{gensub()} when you have

17948

18060

to do substitutions.

17949

18061

17950

@cindex sidebar, Matching the Null String

17951

@ifdocbook

17952

@docbook

17953

<sidebar><title>Matching the Null String</title>

17954

@end docbook

17955

17956

@cindex matching, null strings

17957

@cindex null strings, matching

17958

@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching

17959

@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching

17960

17961

In @command{awk}, the @samp{*} operator can match the null string.

17962

This is particularly important for the @code{sub()}, @code{gsub()},

17963

and @code{gensub()} functions. For example:

17964

17965

@example

17966

$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'}

17967

@print{} XaXbXcX

17968

@end example

17969

17970

@noindent

17971

Although this makes a certain amount of sense, it can be surprising.

17972

17973

@docbook

17974

</sidebar>

17975

@end docbook

17976

@end ifdocbook

17977

17978

@ifnotdocbook

17979

@cartouche

17980

@center @b{Matching the Null String}

17981

17982

17983

@cindex matching, null strings

17984

@cindex null strings, matching

17985

@cindex @code{*} (asterisk), @code{*} operator, null strings@comma{} matching

17986

@cindex asterisk (@code{*}), @code{*} operator, null strings@comma{} matching

17987

17988

In @command{awk}, the @samp{*} operator can match the null string.

17989

This is particularly important for the @code{sub()}, @code{gsub()},

17990

and @code{gensub()} functions. For example:

17991

17992

@example

17993

$ @kbd{echo abc | awk '@{ gsub(/m*/, "X"); print @}'}

17994

@print{} XaXbXcX

17995

@end example

17996

17997

@noindent

17998

Although this makes a certain amount of sense, it can be surprising.

17999

@end cartouche

18000

@end ifnotdocbook

18001

18002

18062

@node I/O Functions

18003

18063

@subsection Input/Output Functions

18004

18064

@cindex input/output functions

18051

18111

18052

18112

@cindex extensions, common@comma{} @code{fflush()} function

18053

18113

@cindex Brian Kernighan's @command{awk}

18054

@code{fflush()} was added to BWK @command{awk} in

18055

April of 1992. For two decades, it was not part of the POSIX standard.

18056

As of December, 2012, it was accepted for inclusion into the POSIX

18057

standard.

18114

Brian Kernighan added @code{fflush()} to his @command{awk} in April

18115

of 1992. For two decades, it was a common extension. In December,

18116

2012, it was accepted for inclusion into the POSIX standard.

18058

18117

See @uref{http://austingroupbugs.net/view.php?id=634, the Austin Group website}.

18059

18118

18060

18119

POSIX standardizes @code{fflush()} as follows: If there

18451

18510

18452

18511

@cindex @command{gawk}, @code{PROCINFO} array in

18453

18512

@cindex @code{PROCINFO} array

18454

@item @code{strftime(} [@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)}

18513

@item @code{strftime(}[@var{format} [@code{,} @var{timestamp} [@code{,} @var{utc-flag}] ] ]@code{)}

18455

18514

@c STARTOFRANGE strf

18456

18515

@cindexgawkfunc{strftime}

18457

18516

@cindex format time string

18557

18616

The full year of the ISO week number, as a decimal number.

18558

18617

18559

18618

@item %h

18560

Equivalent to @samp{%b}.

18619

Equivalent to @code{%b}.

18561

18620

18562

18621

@item %H

18563

18622

The hour (24-hour clock) as a decimal number (00--23).

18626

18685

18627

18686

@item %X

18628

18687

The locale's ``appropriate'' time representation.

18629

(This is @samp{%T} in the @code{"C"} locale.)

18688

(This is @code{%T} in the @code{"C"} locale.)

18630

18689

18631

18690

@item %y

18632

18691

The year modulo 100 as a decimal number (00--99).

18647

18706

@item %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH

18648

18707

@itemx %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy

18649

18708

``Alternate representations'' for the specifications

18650

that use only the second letter (@samp{%c}, @samp{%C},

18709

that use only the second letter (@code{%c}, @code{%C},

18651

18710

and so on).@footnote{If you don't understand any of this, don't worry about

18652

18711

it; these facilities are meant to make it easier to ``internationalize''

18653

18712

programs.

18718

18777

18719

18778

@example

18720

18779

$ date '+Today is %A, %B %d, %Y.'

18721

@print{} Today is Monday, May 05, 2014.

18780

@print{} Today is Monday, September 22, 2014.

18722

18781

@end example

18723

18782

18724

18783

Here is the @command{gawk} version of the @command{date} utility.

18910

18969

right by three bits, you end up with @samp{00010111}.@footnote{This example

18911

18970

shows that 0's come in on the left side. For @command{gawk}, this is

18912

18971

always true, but in some languages, it's possible to have the left side

18913

fill with 1's. Caveat emptor.}

18972

fill with 1's.}

18914

18973

@c Purposely decided to use 0's and 1's here. 2/2001.

18915

If you start over

18916

again with @samp{10111001} and shift it left by three bits, you end up

18917

with @samp{11001000}.

18918

@command{gawk} provides built-in functions that implement the

18919

bitwise operations just described. They are:

18974

If you start over again with @samp{10111001} and shift it left by three

18975

bits, you end up with @samp{11001000}. The following list describes

18976

@command{gawk}'s built-in functions that implement the bitwise operations.

18977

Optional parameters are enclosed in square brackets ([ ]):

18920

18978

18921

18979

@cindex @command{gawk}, bitwise operations in

18922

18980

@table @code

18923

18981

@cindexgawkfunc{and}

18924

18982

@cindex bitwise AND

18925

@item @code{and(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)}

18983

@item @code{and(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)}

18926

18984

Return the bitwise AND of the arguments. There must be at least two.

18927

18985

18928

18986

@cindexgawkfunc{compl}

18937

18995

18938

18996

@cindexgawkfunc{or}

18939

18997

@cindex bitwise OR

18940

@item @code{or(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)}

18998

@item @code{or(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)}

18941

18999

Return the bitwise OR of the arguments. There must be at least two.

18942

19000

18943

19001

@cindexgawkfunc{rshift}

18947

19005

18948

19006

@cindexgawkfunc{xor}

18949

19007

@cindex bitwise XOR

18950

@item @code{xor(@var{v1}, @var{v2}} [@code{,} @dots{}]@code{)}

19008

@item @code{xor(}@var{v1}@code{,} @var{v2} [@code{,} @dots{}]@code{)}

18951

19009

Return the bitwise XOR of the arguments. There must be at least two.

18952

19010

@end table

18953

19011

19070

19128

19071

19129

@command{gawk} provides a single function that lets you distinguish

19072

19130

an array from a scalar variable. This is necessary for writing code

19073

that traverses every element of an array of arrays.

19131

that traverses every element of an array of arrays

19074

19132

(@pxref{Arrays of Arrays}).

19075

19133

19076

19134

@table @code

19086

19144

(not discussed yet; @pxref{User-defined}), to test if a parameter is an

19087

19145

array or not.

19088

19146

19089

Note, however, that using @code{isarray()} at the global level to test

19147

@quotation NOTE

19148

Using @code{isarray()} at the global level to test

19090

19149

variables makes no sense. Since you are the one writing the program, you

19091

19150

are supposed to know if your variables are arrays or not. And in fact,

19092

19151

due to the way @command{gawk} works, if you pass the name of a variable

19093

19152

that has not been previously used to @code{isarray()}, @command{gawk}

19094

will end up turning it into a scalar.

19153

ends up turning it into a scalar.

19154

@end quotation

19095

19155

19096

19156

@node I18N Functions

19097

19157

@subsection String-Translation Functions

19352

19412

function delarray(a, i)

19353

19413

@{

19354

19414

for (i in a)

19355

delete a[i]

19415

delete a[i]

19356

19416

@}

19357

19417

@end example

19358

19418

19363

19423

to repeat this loop everywhere that you need to clear out

19364

19424

an array, your program can just call @code{delarray}.

19365

19425

(This guarantees portability. The use of @samp{delete @var{array}} to delete

19366

the contents of an entire array is a recent@footnote{Late in 2012.}

19426

the contents of an entire array is a relatively recent@footnote{Late in 2012.}

19367

19427

addition to the POSIX standard.)

19368

19428

19369

19429

The following is an example of a recursive function. It takes a string

19393

19453

@print{} !cinaP t'noD

19394

19454

@end example

19395

19455

19396

The C @code{ctime()} function takes a timestamp and returns it in a string,

19456

The C @code{ctime()} function takes a timestamp and returns it as a string,

19397

19457

formatted in a well-known fashion.

19398

19458

The following example uses the built-in @code{strftime()} function

19399

19459

(@pxref{Time Functions})

19408

19468

19409

19469

function ctime(ts, format)

19410

19470

@{

19411

format = PROCINFO["strftime"]

19471

format = "%a %b %e %H:%M:%S %Z %Y"

19472

19412

19473

if (ts == 0)

19413

19474

ts = systime() # use current time as default

19414

19475

return strftime(format, ts)

19415

19476

@}

19416

19477

@c endfile

19417

19478

@end example

19479

19480

You might think that @code{ctime()} could use @code{PROCINFO["strftime"]}

19481

for its format string. That would be a mistake, since @code{ctime()} is

19482

supposed to return the time formatted in a standard fashion, and user-level

19483

code could have changed @code{PROCINFO["strftime"]}.

19418

19484

@c ENDOFRANGE fdef

19419

19485

19420

19486

@node Function Caveats

19986

20052

The last part of the code loops through each function name (from @code{$2} up to

19987

20053

the marker, @samp{data:}), calling the function named by the field. The indirect

19988

20054

function call itself occurs as a parameter in the call to @code{printf}.

19989

(The @code{printf} format string uses @samp{%s} as the format specifier so that we

20055

(The @code{printf} format string uses @code{%s} as the format specifier so that we

19990

20056

can use functions that return strings, as well as numbers. Note that the result

19991

20057

from the indirect call is concatenated with the empty string, in order to force

19992

20058

it to be a string value.)

20063

20129

20064

20130

# quicksort_swap --- helper function for quicksort, should really be inline

20065

20131

20066

function quicksort_swap(data, i, j, temp)

20132

function quicksort_swap(data, i, j, temp)

20067

20133

@{

20068

20134

temp = data[i]

20069

20135

data[i] = data[j]

20214

20280

20215

20281

@item

20216

20282

POSIX @command{awk} provides three kinds of built-in functions: numeric,

20217

string, and I/O. @command{gawk} provides functions that work with values

20218

representing time, do bit manipulation, sort arrays, and internationalize

20219

and localize programs. @command{gawk} also provides several extensions to

20220

some of standard functions, typically in the form of additional arguments.

20283

string, and I/O. @command{gawk} provides functions that sort arrays, work

20284

with values representing time, do bit manipulation, determine variable

20285

type (array vs.@: scalar), and internationalize and localize programs.

20286

@command{gawk} also provides several extensions to some of standard

20287

functions, typically in the form of additional arguments.

20221

20288

20222

20289

@item

20223

20290

Functions accept zero or more arguments and return a value. The

20468

20535

function lib_func(x, y, l1, l2)

20469

20536

@{

20470

20537

@dots{}

20471

@var{use variable} some_var # some_var should be local

20472

@dots{} # but is not by oversight

20538

# some_var should be local but by oversight is not

20539

@var{use variable} some_var

20540

@dots{}

20473

20541

@}

20474

20542

@end example

20475

20543

20580

20648

# a[5] = "123.45"

20581

20649

# a[6] = "1.e3"

20582

20650

# a[7] = "1.32"

20583

# a[7] = "1.32E2"

20651

# a[8] = "1.32E2"

20584

20652

#

20585

20653

# for (i = 1; i in a; i++)

20586

20654

# print a[i], strtonum(a[i]), mystrtonum(a[i])

20591

20659

The function first looks for C-style octal numbers (base 8).

20592

20660

If the input string matches a regular expression describing octal

20593

20661

numbers, then @code{mystrtonum()} loops through each character in the

20594

string. It sets @code{k} to the index in @code{"01234567"} of the current

20595

octal digit. Since the return value is one-based, the @samp{k--}

20596

adjusts @code{k} so it can be used in computing the return value.

20662

string. It sets @code{k} to the index in @code{"1234567"} of the current

20663

octal digit.

20664

The return value will either be the same number as the digit, or zero

20665

if the character is not there, which will be true for a @samp{0}.

20666

This is safe, since the regexp test in the @code{if} ensures that

20667

only octal values are converted.

20597

20668

20598

20669

Similar logic applies to the code that checks for and converts a

20599

20670

hexadecimal value, which starts with @samp{0x} or @samp{0X}.

20626

20697

particular computation, you make a statement about what you believe to be

20627

20698

the case. Such a statement is known as an

20628

20699

@dfn{assertion}. The C language provides an @code{<assert.h>} header file

20629

and corresponding @code{assert()} macro that the programmer can use to make

20700

and corresponding @code{assert()} macro that a programmer can use to make

20630

20701

assertions. If an assertion fails, the @code{assert()} macro arranges to

20631

20702

print a diagnostic message describing the condition that should have

20632

20703

been true but was not, and then it kills the program. In C, using

21096

21167

now = systime()

21097

21168

21098

21169

# return date(1)-style output

21099

ret = strftime(PROCINFO["strftime"], now)

21170

ret = strftime("%a %b %e %H:%M:%S %Z %Y", now)

21100

21171

21101

21172

# clear out target array

21102

21173

delete time

21211

21282

This tests the result to see if it is empty or not. An equivalent

21212

21283

test would be @samp{contents == ""}.

21213

21284

21285

@xref{Extension Sample Readfile}, for an extension function that

21286

also reads an entire file into memory.

21287

21214

21288

@node Data File Management

21215

21289

@section @value{DDF} Management

21216

21290

21268

21342

@c # Arnold Robbins, arnold@@skeeve.com, Public Domain

21269

21343

@c # January 1992

21270

21344

21271

FILENAME != _oldfilename \

21272

@{

21345

FILENAME != _oldfilename @{

21273

21346

if (_oldfilename != "")

21274

21347

endfile(_oldfilename)

21275

21348

_oldfilename = FILENAME

21276

21349

beginfile(FILENAME)

21277

21350

@}

21278

21351

21279

END @{ endfile(FILENAME) @}

21352

END @{ endfile(FILENAME) @}

21280

21353

@end example

21281

21354

21282

21355

This file must be loaded before the user's ``main'' program, so that the

21329

21402

beginfile(FILENAME)

21330

21403

@}

21331

21404

21332

END @{ endfile(_filename_) @}

21405

END @{ endfile(_filename_) @}

21333

21406

@c endfile

21334

21407

@end example

21335

21408

21428

21501

@c endfile

21429

21502

@end example

21430

21503

21431

This code relies on the @code{ARGIND} variable

21432

(@pxref{Auto-set}),

21433

which is specific to @command{gawk}.

21434

If you are not using

21435

@command{gawk}, you can use ideas presented in

21436

@ifnotinfo

21437

the previous @value{SECTION}

21438

@end ifnotinfo

21439

@ifinfo

21440

@ref{Filetrans Function},

21441

@end ifinfo

21442

to either update @code{ARGIND} on your own

21443

or modify this code as appropriate.

21444

21445

The @code{rewind()} function also relies on the @code{nextfile} keyword

21446

(@pxref{Nextfile Statement}). Because of this, you should not call it

21447

from an @code{ENDFILE} rule. (This isn't necessary anyway, since as soon

21448

as an @code{ENDFILE} rule finishes @command{gawk} goes to the next file!)

21504

The @code{rewind()} function relies on the @code{ARGIND} variable

21505

(@pxref{Auto-set}), which is specific to @command{gawk}. It also

21506

relies on the @code{nextfile} keyword (@pxref{Nextfile Statement}).

21507

Because of this, you should not call it from an @code{ENDFILE} rule.

21508

(This isn't necessary anyway, since as soon as an @code{ENDFILE} rule

21509

finishes @command{gawk} goes to the next file!)

21449

21510

21450

21511

@node File Checking

21451

21512

@subsection Checking for Readable @value{DDF}s

21478

21539

21479

21540

BEGIN @{

21480

21541

for (i = 1; i < ARGC; i++) @{

21481

if (ARGV[i] ~ /^[[:alpha:]_][[:alnum:]_]*=.*/ \

21542

if (ARGV[i] ~ /^[a-zA-Z_][a-zA-Z0-9_]*=.*/ \

21482

21543

|| ARGV[i] == "-" || ARGV[i] == "/dev/stdin")

21483

21544

continue # assignment or standard input

21484

21545

else if ((getline junk < ARGV[i]) < 0) # unreadable

21496

21557

skips the file (since it's no longer in the list).

21497

21558