~vcs-imports/gawk/master

« back to all changes in this revision

Viewing changes to doc/gawk.1

• browse files at revision 291
• compare with another revision
• download diff
• download tarball
• view history from revision 291

Show diffs side-by-side

added

removed

doc/gawk.1

33

33

]

34

34

.I program-text

35

35

file .\|.\|.

36

 

.sp

37

 

.B pgawk

38

 

[ \*(PX or \*(GN style options ]

39

 

.B \-f

40

 

.I program-file

41

 

[

42

 

.B \-\^\-

43

 

] file .\|.\|.

44

 

.br

45

 

.B pgawk

46

 

[ \*(PX or \*(GN style options ]

47

 

[

48

 

.B \-\^\-

49

 

]

50

 

.I program-text

51

 

file .\|.\|.

52

 

.sp

53

 

.B dgawk

54

 

[ \*(PX or \*(GN style options ]

55

 

.B \-f

56

 

.I program-file

57

 

[

58

 

.B \-\^\-

59

 

] file .\|.\|.

60

36

.SH DESCRIPTION

61

37

.I Gawk

62

38

is the \*(GN Project's implementation of the \*(AK programming language.

84

60

.B ARGV

85

61

pre-defined \*(AK variables.

86

62

.PP

87

 

.I Pgawk

88

 

is the profiling version of

89

 

.IR gawk .

90

 

It is identical in every way to

91

 

.IR gawk ,

92

 

except that programs run more slowly,

93

 

and it automatically produces an execution profile in the file

 

63

When 

 

64

.I gawk

 

65

is invoked with the

 

66

.B \-\^\-profile

 

67

option, it starts gathering profiling statistics

 

68

from the execution of the program.

 

69

.I Gawk

 

70

runs more slowly in this mode, and automatically produces an execution

 

71

profile in the file

94

72

.B awkprof.out

95

73

when done.

96

74

See the

97

75

.B \-\^\-profile

98

76

option, below.

99

77

.PP

100

 

.I Dgawk

101

 

is an

102

 

.I awk

103

 

debugger. Instead of running the program directly, it loads the

 

78

.I Gawk

 

79

also has an integrated debugger. An interactive debugging session can

 

80

be started by supplying the

 

81

.B \-\^\-debug

 

82

option to the command line. In this mode of execution,

 

83

.I gawk

 

84

loads the

104

85

AWK source code and then prompts for debugging commands.

105

 

Unlike

106

 

.IR gawk " and " pgawk ", " dgawk

107

 

only processes AWK program source provided with the

 

86

.I Gawk

 

87

can only debug AWK program source provided with the

108

88

.B \-f

109

89

option.

110

90

The debugger is documented in \*(EP.

273

253

and so on.)

274

254

.TP

275

255

.PD 0

 

256

\fB\-D\fR[\fIfile\fR]

 

257

.TP

 

258

.PD

 

259

\fB\-\^\-debug\fR[\fB=\fIfile\fR]

 

260

Enable debugging of \*(AK programs.

 

261

By default, the debugger reads commands interactively from the terminal.

 

262

The optional

 

263

.IR file

 

264

argument can be used to specify a file with a list

 

265

of commands for the debugger to execute non-interactively.

 

266

.TP

 

267

.PD 0

276

268

.BI "\-e " program-text

277

269

.TP

278

270

.PD

331

323

these options cause an immediate, successful exit.)

332

324

.TP

333

325

.PD 0

 

326

.BI "\-l " lib

 

327

.TP

 

328

.PD

 

329

.BI \-\^\-load " lib"

 

330

Load a shared library

 

331

.IR lib .

 

332

This searches for the library using the

 

333

.B AWKPATH

 

334

environment variable. The suffix 

 

335

.I .so

 

336

in the library name is optional, and

 

337

the library initialization routine is expected to be named

 

338

.BR dlload() .

 

339

.TP

 

340

.PD 0

334

341

.BR "\-L " [ \fIvalue\fR ]

335

342

.TP

336

343

.PD

387

394

..

388

395

.TP

389

396

.PD 0

 

397

\fB\-o\fR[\fIfile\fR]

 

398

.TP

 

399

.PD

 

400

\fB\-\^\-pretty-print\fR[\fB=\fIfile\fR]

 

401

Output a pretty printed version of the program to

 

402

.IR file .

 

403

If no

 

404

.I file

 

405

is provided,

 

406

.I gawk

 

407

uses a file named

 

408

.B awkprof.out

 

409

in the current directory.

 

410

.TP

 

411

.PD 0

390

412

.B \-O

391

413

.TP

392

414

.PD

393

415

.B \-\^\-optimize

394

416

Enable optimizations upon the internal representation of the program.

395

 

Currently, this includes just simple constant-folding. The

 

417

Currently, this includes simple constant-folding, and tail call

 

418

elimination for recursive functions. The

396

419

.I gawk

397

420

maintainer hopes to add additional optimizations over time.

398

421

.TP

401

424

.TP

402

425

.PD

403

426

\fB\-\^\-profile\fR[\fB=\fIprof_file\fR]

404

 

Send profiling data to

 

427

Start a profiling session, and send the profiling data to

405

428

.IR prof_file .

406

429

The default is

407

430

.BR awkprof.out .

408

 

When run with

409

 

.IR gawk ,

410

 

the profile is just a \*(lqpretty printed\*(rq version of the program.

411

 

When run with

412

 

.IR pgawk ,

413

 

the profile contains execution counts of each statement in the program

 

431

The profile contains execution counts of each statement in the program

414

432

in the left margin and function call counts for each user-defined function.

415

433

.TP

416

434

.PD 0

482

500

.BR \-\^-traditional .

483

501

.TP

484

502

.PD 0

485

 

.B \-R

486

 

.TP

487

 

.PD

488

 

.BI \-\^\-command " file"

489

 

.I Dgawk

490

 

only.  Read stored debugger commands from

491

 

.IR file .

492

 

.TP

493

 

.PD 0

494

503

.BI \-S

495

504

.TP

496

505

.PD

3122

3131

it is unlikely to go away. Additional mechanisms may

3123

3132

be added at some point.

3124

3133

.SH SIGNALS

3125

 

.I pgawk

3126

 

accepts two signals.

 

3134

The

 

3135

.I gawk

 

3136

profiler accepts two signals.

3127

3137

.B SIGUSR1

3128

3138

causes it to dump a profile and function call stack to the

3129

3139

profile file, which is either

3133

3143

option.  It then continues to run.

3134

3144

.B SIGHUP

3135

3145

causes

3136

 

.I pgawk

 

3146

.I gawk

3137

3147

to dump the profile and function call stack and then exit.

3138

3148

.SH INTERNATIONALIZATION

3139

3149

.PP

• Older »

Loggerhead is a web-based interface for Breezy
Version: 2.0.1