1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
|
'\" et
.TH PATCH "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
patch
\(em apply changes to files
.SH SYNOPSIS
.LP
.nf
patch \fB[\fR-blNR\fB] [\fR-c|-e|-n|-u\fB] [\fR-d \fIdir\fB] [\fR-D \fIdefine\fB] [\fR-i \fIpatchfile\fB]
[\fR-o \fIoutfile\fB] [\fR-p \fInum\fB] [\fR-r \fIrejectfile\fB] [\fIfile\fB]\fR
.fi
.SH DESCRIPTION
The
.IR patch
utility shall read a source (patch) file containing any of four
forms of difference (diff) listings produced by the
.IR diff
utility (normal, copied context, unified context, or in the style of
.IR ed )
and apply those differences to a file. By default,
.IR patch
shall read from the standard input.
.P
The
.IR patch
utility shall attempt to determine the type of the
.IR diff
listing, unless overruled by a
.BR \-c ,
.BR \-e ,
.BR \-n ,
or
.BR \-u
option.
.P
If the patch file contains more than one patch,
.IR patch
shall attempt to apply each of them as if they came from separate patch
files. (In this case, the application shall ensure that the name of the
patch file is determinable for each
.IR diff
listing.)
.SH OPTIONS
The
.IR patch
utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The following options shall be supported:
.IP "\fB\-b\fP" 10
Save a copy of the original contents of each modified file, before the
differences are applied, in a file of the same name with the suffix
.BR .orig
appended to it. If the file already exists, it shall be overwritten;
if multiple patches are applied to the same file, the
.BR .orig
file shall be written only for the first patch. When the
.BR \-o
.IR outfile
option is also specified,
.IR file \c
.BR .orig
shall not be created but, if
.IR outfile
already exists,
.IR outfile \c
.BR .orig
shall be created.
.IP "\fB\-c\fP" 10
Interpret the patch file as a copied context difference (the output
of the utility
.IR diff
when the
.BR \-c
or
.BR \-C
options are specified).
.IP "\fB\-d\ \fIdir\fR" 10
Change the current directory to
.IR dir
before processing as described in the EXTENDED DESCRIPTION section.
.IP "\fB\-D\ \fIdefine\fR" 10
Mark changes with one of the following C preprocessor constructs:
.RS 10
.sp
.RS 4
.nf
#ifdef define
\&...
#endif
.P
#ifndef define
\&...
#endif
.fi
.P
.RE
.P
optionally combined with the C preprocessor construct
.BR #else .
If the patched file is processed with the C preprocessor, where the
macro
.IR define
is defined, the output shall contain the changes from the patch file;
otherwise, the output shall not contain the patches specified in the
patch file.
.RE
.IP "\fB\-e\fP" 10
Interpret the patch file as an
.IR ed
script, rather than a
.IR diff
script.
.IP "\fB\-i\ \fIpatchfile\fR" 10
Read the patch information from the file named by the pathname
.IR patchfile ,
rather than the standard input.
.IP "\fB\-l\fP" 10
(The letter ell.) Cause any sequence of
<blank>
characters in the difference script to match any sequence of
<blank>
characters in the input file. Other characters shall be matched exactly.
.IP "\fB\-n\fP" 10
Interpret the script as a normal difference.
.IP "\fB\-N\fP" 10
Ignore patches where the differences have already been applied to the
file; by default, already-applied patches shall be rejected.
.IP "\fB\-o\ \fIoutfile\fR" 10
Instead of modifying the files (specified by the
.IR file
operand or the difference listings) directly, write a copy of the file
referenced by each patch, with the appropriate differences applied, to
.IR outfile .
Multiple patches for a single file shall be applied to the intermediate
versions of the file created by any previous patches, and shall result
in multiple, concatenated versions of the file being written to
.IR outfile .
.IP "\fB\-p\ \fInum\fR" 10
For all pathnames in the patch file that indicate the names of files to
be patched, delete
.IR num
pathname components from the beginning of each pathname. If the
pathname in the patch file is absolute, any leading
<slash>
characters shall be considered the first component (that is,
.BR "\-p\ 1"
shall remove the leading
<slash>
characters). Specifying
.BR "\-p\ 0"
shall cause the full pathname to be used. If
.BR \-p
is not specified, only the basename (the final pathname component)
shall be used.
.IP "\fB\-R\fP" 10
Reverse the sense of the patch script; that is, assume that the
difference script was created from the new version to the old version.
The
.BR \-R
option cannot be used with
.IR ed
scripts. The
.IR patch
utility shall attempt to reverse each portion of the script before
applying it. Rejected differences shall be saved in swapped format. If
this option is not specified, and until a portion of the patch file is
successfully applied,
.IR patch
attempts to apply each portion in its reversed sense as well as in its
normal sense. If the attempt is successful, the user shall be prompted
to determine whether the
.BR \-R
option should be set.
.IP "\fB\-r\ \fIrejectfile\fR" 10
Override the default reject filename. In the default case, the reject
file shall have the same name as the output file, with the suffix
.BR .rej
appended to it; see
.IR "Patch Application".
.IP "\fB\-u\fR" 10
Interpret the patch file as a unified context difference (the output
of the
.IR diff
utility when the
.BR \-u
or
.BR \-U
options are specified).
.SH OPERANDS
The following operand shall be supported:
.IP "\fIfile\fR" 10
A pathname of a file to patch.
.SH STDIN
See the INPUT FILES section.
.SH "INPUT FILES"
Input files shall be text files.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR patch :
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 8.2" ", " "Internationalization Variables"
the precedence of internationalization variables used to determine the
values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_COLLATE\fP" 10
.br
Determine the locale for the behavior of ranges, equivalence classes,
and multi-character collating elements used in the extended regular
expression defined for the
.BR yesexpr
locale keyword in the
.IR LC_MESSAGES
category.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of text
data as characters (for example, single-byte as opposed to multi-byte
characters in arguments and input files), and the behavior of character
classes used in the extended regular expression defined for the
.BR yesexpr
locale keyword in the
.IR LC_MESSAGES
category.
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale used to process affirmative responses, and the
locale used to affect the format and contents of diagnostic messages
and prompts written to standard error.
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fILC_TIME\fP" 10
Determine the locale for recognizing the format of file timestamps
written by the
.IR diff
utility in a context-difference input file.
.SH "ASYNCHRONOUS EVENTS"
Default.
.SH STDOUT
Not used.
.SH STDERR
The standard error shall be used for diagnostic and informational
messages.
.SH "OUTPUT FILES"
The output of the
.IR patch
utility, the save files (\c
.BR .orig
suffixes), and the reject files (\c
.BR .rej
suffixes) shall be text files.
.SH "EXTENDED DESCRIPTION"
A patch file may contain patching instructions for more than one file;
filenames shall be determined as specified in
.IR "Filename Determination".
When the
.BR \-b
option is specified, for each patched file, the original shall be saved
in a file of the same name with the suffix
.BR .orig
appended to it.
.P
For each patched file, a reject file may also be created as noted in
.IR "Patch Application".
In the absence of a
.BR \-r
option, the name of this file shall be formed by appending the suffix
.BR .rej
to the original filename.
.SS "Patch File Format"
.P
The patch file shall contain zero or more lines of header information
followed by one or more patches. Each patch shall contain zero or more
lines of filename identification in the format produced by the
.BR \-c ,
.BR \-C ,
.BR \-u ,
or
.BR \-U
options of the
.IR diff
utility, and one or more sets of
.IR diff
output, which are customarily called \fIhunks\fP.
.P
The
.IR patch
utility shall recognize the following expression in the header
information:
.IP "\fBIndex:\ \fIpathname\fR" 6
.br
The file to be patched is named
.IR pathname .
.P
If all lines (including headers) within a patch begin with the same
leading sequence of
<blank>
characters, the
.IR patch
utility shall remove this sequence before proceeding. Within each
patch, if the type of difference is common context, the
.IR patch
utility shall recognize the following expressions:
.IP "***\ \fIfilename\ timestamp\fR" 6
.br
The patches arose from
.IR filename .
.IP "\-\|\-\|\-\ \fIfilename\ timestamp\fR" 6
.br
The patches should be applied to
.IR filename .
.P
If the type of difference is unified context, the
.IR patch
utility shall recognize the following expressions:
.IP "\-\|\-\|\-\ \fIfilename\ timestamp\fR" 6
.br
The patches arose from
.IR filename .
.IP "+\|+\|+\ \fIfilename\ timestamp\fR" 6
.br
The patches should be applied to
.IR filename .
.P
Each hunk within a patch shall be the
.IR diff
output to change a line range within the original file. The line
numbers for successive hunks within a patch shall occur in ascending
order.
.SS "Filename Determination"
.P
If no
.IR file
operand is specified,
.IR patch
shall perform the following steps to determine the filename to use:
.IP " 1." 4
If the type of
.IR diff
is context, the
.IR patch
utility shall delete pathname components (as specified by the
.BR \-p
option) from the filename on the line beginning with
.BR \(dq***\(dq
(if copied context) or
.BR \(dq---\(dq
(if unified context), then test for the existence of this file relative
to the current directory (or the directory specified with the
.BR \-d
option). If the file exists, the
.IR patch
utility shall use this filename.
.IP " 2." 4
If the type of
.IR diff
is context, the
.IR patch
utility shall delete the pathname components (as specified by the
.BR \-p
option) from the filename on the line beginning with
.BR \(dq---\(dq
(if copied context) or
.BR \(dq+\|+\|+\(dq
(if unified context), then test for the existence of this file relative
to the current directory (or the directory specified with the
.BR \-d
option). If the file exists, the
.IR patch
utility shall use this filename.
.IP " 3." 4
If the header information contains a line beginning with the string
.BR Index: ,
the
.IR patch
utility shall delete pathname components (as specified by the
.BR \-p
option) from this line, then test for the existence of this file
relative to the current directory (or the directory specified with the
.BR \-d
option). If the file exists, the
.IR patch
utility shall use this filename.
.IP " 4." 4
If an
.BR SCCS
directory exists in the current directory,
.IR patch
shall attempt to perform a
.IR get
.BR \-e
.BR SCCS/s. \c
.IR filename
command to retrieve an editable version of the file. If the file
exists, the
.IR patch
utility shall use this filename.
.IP " 5." 4
The
.IR patch
utility shall write a prompt to standard output and request a filename
interactively from the controlling terminal (for example,
.BR /dev/tty ).
.SS "Patch Application"
.P
If the
.BR \-c ,
.BR \-e ,
.BR \-n ,
or
.BR \-u
option is present, the
.IR patch
utility shall interpret information within each hunk as a copied context
difference, an
.IR ed
difference, a normal difference, or a unified context difference,
respectively. In the absence of any of these options, the
.IR patch
utility shall determine the type of difference based on the format of
information within the hunk.
.P
For each hunk, the
.IR patch
utility shall begin to search for the place to apply the patch at the
line number at the beginning of the hunk, plus or minus any offset used
in applying the previous hunk. If lines matching the hunk context are
not found,
.IR patch
shall scan both forwards and backwards at least 1\|000 bytes for a set
of lines that match the hunk context.
.P
If no such place is found and it is a context difference, then another
scan shall take place, ignoring the first and last line of context. If
that fails, the first two and last two lines of context shall be
ignored and another scan shall be made. Implementations may search
more extensively for installation locations.
.P
If no location can be found, the
.IR patch
utility shall append the hunk to the reject file. A rejected hunk that
is a copied context difference, an
.IR ed
difference, or a normal difference shall be written in
copied-context-difference format regardless of the format of the patch
file. It is implementation-defined whether a rejected hunk that is
a unified context difference is written in copied-context-difference
format or in unified-context-difference format.
If the input was a normal or
.IR ed -style
difference, the reject file may contain differences with zero lines of
context. The line numbers on the hunks in the reject file may be
different from the line numbers in the patch file since they shall
reflect the approximate locations for the failed hunks in the new file
rather than the old one.
.P
If the type of patch is an
.IR ed
diff, the implementation may accomplish the patching by invoking the
.IR ed
utility.
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
Successful completion.
.IP "\01" 6
One or more lines were written to a reject file.
.IP >1 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
Patches that cannot be correctly placed in the file shall be written to
a reject file.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
The
.BR \-R
option does not work with
.IR ed
scripts because there is too little information to reconstruct the
reverse operation.
.P
The
.BR \-p
option makes it possible to customize a patch file to local user
directory structures without manually editing the patch file. For
example, if the filename in the patch file was:
.sp
.RS 4
.nf
/curds/whey/src/blurfl/blurfl.c
.fi
.P
.RE
.P
Setting
.BR "\-p\ 0"
gives the entire pathname unmodified;
.BR "\-p\ 1"
gives:
.sp
.RS 4
.nf
curds/whey/src/blurfl/blurfl.c
.fi
.P
.RE
.P
without the leading
<slash>,
.BR "\-p\ 4"
gives:
.sp
.RS 4
.nf
blurfl/blurfl.c
.fi
.P
.RE
.P
and not specifying
.BR \-p
at all gives:
.sp
.RS 4
.nf
blurfl.c .
.fi
.P
.RE
.SH EXAMPLES
None.
.SH RATIONALE
Some of the functionality in historical
.IR patch
implementations was not specified. The following documents those
features present in historical implementations that have not been
specified.
.P
A deleted piece of functionality was the
.BR '\(pl'
pseudo-option allowing an additional set of options and a patch file
operand to be given. This was seen as being insufficiently useful to
standardize.
.P
In historical implementations, if the string
.BR \(dqPrereq:\(dq
appeared in the header, the
.IR patch
utility would search for the corresponding version information (the
string specified in the header, delimited by
<blank>
characters or the beginning or end of a line or the file) anywhere in
the original file. This was deleted as too simplistic and insufficiently
trustworthy a mechanism to standardize. For example, if:
.sp
.RS 4
.nf
Prereq: 1.2
.fi
.P
.RE
.P
were in the header, the presence of a delimited 1.2 anywhere in the
file would satisfy the prerequisite.
.P
The following options were dropped from historical implementations of
.IR patch
as insufficiently useful to standardize:
.IP "\fB\-b\fP" 10
The
.BR \-b
option historically provided a method for changing the name extension
of the backup file from the default
.BR .orig .
This option has been modified and retained in this volume of POSIX.1\(hy2017.
.IP "\fB\-F\fP" 10
The
.BR \-F
option specified the number of lines of a context diff to ignore when
searching for a place to install a patch.
.IP "\fB\-f\fP" 10
The
.BR \-f
option historically caused
.IR patch
not to request additional information from the user.
.IP "\fB\-r\fP" 10
The
.BR \-r
option historically provided a method of overriding the extension of
the reject file from the default
.BR .rej .
.IP "\fB\-s\fP" 10
The
.BR \-s
option historically caused
.IR patch
to work silently unless an error occurred.
.IP "\fB\-x\fP" 10
The
.BR \-x
option historically set internal debugging flags.
.P
In some file system implementations, the saving of a
.BR .orig
file may produce unwanted results. In the case of 12, 13, or
14-character filenames (on file systems supporting 14-character
maximum filenames), the
.BR .orig
file overwrites the new file. The reject file may also exceed this
filename limit. It was suggested, due to some historical practice,
that a
<tilde>
(\c
.BR '\(ti' )
suffix be used instead of
.BR .orig
and some other character instead of the
.BR .rej
suffix. This was rejected because it is not obvious to the user which
file is which. The suffixes
.BR .orig
and
.BR .rej
are clearer and more understandable.
.P
The
.BR \-b
option has the opposite sense in some historical implementations\(emdo
not save the
.BR .orig
file. The default case here is not to save the files, making
.IR patch
behave more consistently with the other standard utilities.
.P
The
.BR \-w
option in early proposals was changed to
.BR \-l
to match historical practice.
.P
The
.BR \-N
option was included because without it, a non-interactive application
cannot reject previously applied patches. For example, if a user is
piping the output of
.IR diff
into the
.IR patch
utility, and the user only wants to patch a file to a newer version
non-interactively, the
.BR \-N
option is required.
.P
Changes to the
.BR \-l
option description were proposed to allow matching across
<newline>
characters in addition to just
<blank>
characters. Since this is not historical practice, and since some
ambiguities could result, it is suggested that future developments in
this area utilize another option letter, such as
.BR \-L .
.P
The
.BR \-u
option of GNU
.IR patch
has been added, along with support for unified context formats.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIdiff\fR\^",
.IR "\fIed\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|