Debian Codegraph @

upstream/debian-unstable/man3/inplace.3am

raw
1 .TH INPLACE 3am "Feb 29 2024" "Free Software Foundation" "GNU Awk Extension Modules"
2 .SH NAME
3 inplace \- emulate sed/perl/ruby in-place editing
4 .SH SYNOPSIS
5 .ft CW
6 .nf
7 gawk -i inplace ...
8 .fi
9 .ft R
10 .SH DESCRIPTION
11 The
12 .I inplace
13 extension adds two functions named
14 .B inplace_begin()
15 and
16 .BR inplace_end() .
17 These functions are meant to be invoked from the
18 .I inplace.awk
19 wrapper which is installed when
20 .I gawk
21 is.
22 .PP
23 By default, each named file on the command line is
24 replaced with a new file of the same name whose contents
25 are the results of running the AWK program.
26 Since a new file is created, if the file is a link (whether hard
27 or symbolic), the link will be broken.
28 This behavior is consistent with GNU
29 .I sed
30 which also breaks links when the
31 .B \-i
32 or
33 .B \-\^\-in\-place
34 flag is used.
35 If the user supplies an AWK variable named
36 .B inplace::suffix
37 in a
38 .B BEGIN
39 rule or on the command line, then the
40 .I inplace
41 extension concatenates that suffix onto the original
42 filename and uses the result as a filename for renaming
43 the original.
44 .PP
45 For backwards compatibility, the variable will also check
46 .B INPLACE_SUFFIX
47 (in the
48 .B awk
49 namespace) for the suffix to use if
50 .B inplace::suffix
51 is not set.
52 .PP
53 One can disable inplace editing selectively by placing
54 .B inplace::enable=0
55 on the command line prior to files that should be processed normally.
56 One can reenable inplace editing by placing
57 .B inplace::enable=1
58 prior to files that should be subject to inplace editing.
59 .\" .SH NOTES
60 .SH BUGS
61 While the extension does attempt to preserve ownership and permissions,
62 it makes no attempt to copy the ACLs from the original file.
63 .PP
64 If the program dies prematurely, as might happen if an unhandled signal
65 is received, a temporary file may be left behind.
66 .SH EXAMPLE
67 .ft CW
68 .nf
69 gawk -i inplace '\f(CIscript\fP' files ...
70 .br
71 gawk -i inplace -f \f(CIscriptfile\fP files ...
72 .fi
73 .ft R
74 .SH "SEE ALSO"
75 .IR "GAWK: Effective AWK Programming" ,
76 .IR filefuncs (3am),
77 .IR fnmatch (3am),
78 .IR fork (3am),
79 .IR ordchr (3am),
80 .IR readdir (3am),
81 .IR readfile (3am),
82 .IR revoutput (3am),
83 .IR rwarray (3am).
84 .SH AUTHOR
85 Andrew Schorr,
86 .BR [email protected] .
87 .SH COPYING PERMISSIONS
88 Copyright \(co 2012, 2013, 2015, 2018, 2019, 2024,
89 Free Software Foundation, Inc.
90 .PP
91 Permission is granted to make and distribute verbatim copies of
92 this manual page provided the copyright notice and this permission
93 notice are preserved on all copies.
94 .ig
95 Permission is granted to process this file through troff and print the
96 results, provided the printed document carries copying permission
97 notice identical to this one except for the removal of this paragraph
98 (this paragraph not being relevant to the printed manual page).
99 ..
100 .PP
101 Permission is granted to copy and distribute modified versions of this
102 manual page under the conditions for verbatim copying, provided that
103 the entire resulting derived work is distributed under the terms of a
104 permission notice identical to this one.
105 .PP
106 Permission is granted to copy and distribute translations of this
107 manual page into another language, under the above conditions for
108 modified versions, except that this permission notice may be stated in
109 a translation approved by the Foundation.
110 .\" vim: set filetype=nroff :