Provided by: manpages-posix_2013a-2_all bug

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.

NAME

       sed — stream editor

SYNOPSIS

       sed [−n] script [file...]

       sed [−n] −e script [−e script]... [−f script_file]... [file...]

       sed [−n] [−e script]... −f script_file [−f script_file]... [file...]

DESCRIPTION

       The sed utility is a stream editor that shall read one or more text files, make editing changes according
       to  a  script of editing commands, and write the results to standard output. The script shall be obtained
       from either the script operand string or a combination of the option-arguments from the −e script and  −f
       script_file options.

OPTIONS

       The  sed  utility  shall  conform  to  the Base Definitions volume of POSIX.1‐2008, Section 12.2, Utility
       Syntax Guidelines, except that the order of presentation of the −e and −f options is significant.

       The following options shall be supported:

       −e script Add the editing commands specified by the script option-argument to the end of  the  script  of
                 editing commands.

       −f script_file
                 Add the editing commands in the file script_file to the end of the script of editing commands.

       −n        Suppress  the  default output (in which each line, after it is examined for editing, is written
                 to standard output). Only lines explicitly selected for output are written.

       If any −e or −f options are specified, the script of editing  commands  shall  initially  be  empty.  The
       commands specified by each −e or −f option shall be added to the script in the order specified. When each
       addition  is  made, if the previous addition (if any) was from a −e option, a <newline> shall be inserted
       before the new addition. The resulting script shall have the  same  properties  as  the  script  operand,
       described in the OPERANDS section.

OPERANDS

       The following operands shall be supported:

       file      A  pathname  of  a  file  whose  contents  are  read  and edited. If multiple file operands are
                 specified, the named files shall be read in the order specified and the concatenation shall  be
                 edited. If no file operands are specified, the standard input shall be used.

       script    A  string  to  be  used  as the script of editing commands. The application shall not present a
                 script that violates the restrictions of a text file except that the final character  need  not
                 be a <newline>.

STDIN

       The  standard  input shall be used if no file operands are specified, and shall be used if a file operand
       is '−' and the implementation treats the '−' as meaning standard input.  Otherwise,  the  standard  input
       shall not be used.  See the INPUT FILES section.

INPUT FILES

       The  input  files  shall  be text files. The script_files named by the −f option shall consist of editing
       commands.

ENVIRONMENT VARIABLES

       The following environment variables shall affect the execution of sed:

       LANG      Provide a default value for the internationalization variables that are unset or null. (See the
                 Base Definitions volume of POSIX.1‐2008, Section 8.2, Internationalization  Variables  for  the
                 precedence   of   internationalization  variables  used  to  determine  the  values  of  locale
                 categories.)

       LC_ALL    If set to a non-empty string value, override the values of all the  other  internationalization
                 variables.

       LC_COLLATE
                 Determine  the  locale  for  the  behavior  of ranges, equivalence classes, and multi-character
                 collating elements within regular expressions.

       LC_CTYPE  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 within regular expressions.

       LC_MESSAGES
                 Determine the locale that should be used to  affect  the  format  and  contents  of  diagnostic
                 messages written to standard error.

       NLSPATH   Determine the location of message catalogs for the processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       The  input  files  shall be written to standard output, with the editing commands specified in the script
       applied. If the −n option is specified, only those input lines selected by the script shall be written to
       standard output.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       The output files shall be text files whose formats are dependent on the editing commands given.

EXTENDED DESCRIPTION

       The script shall consist of editing commands of the following form:

           [address[,address]]function

       where function represents a single-character command verb from the  list  in  Editing  Commands  in  sed,
       followed by any applicable arguments.

       The  command  can  be  preceded  by <blank> characters and/or <semicolon> characters. The function can be
       preceded by <blank> characters. These optional characters shall have no effect.

       In default operation, sed cyclically shall append  a  line  of  input,  less  its  terminating  <newline>
       character,  into the pattern space. Reading from input shall be skipped if a <newline> was in the pattern
       space prior to a D command ending the previous cycle. The sed utility shall then apply  in  sequence  all
       commands whose addresses select that pattern space, until a command starts the next cycle or quits. If no
       commands  explicitly started a new cycle, then at the end of the script the pattern space shall be copied
       to standard output (except when −n is specified) and the pattern space shall  be  deleted.  Whenever  the
       pattern  space  is  written  to  standard  output or a named file, sed shall immediately follow it with a
       <newline>.

       Some of the editing commands use a hold space to save all or part of the  pattern  space  for  subsequent
       retrieval. The pattern and hold spaces shall each be able to hold at least 8192 bytes.

   Addresses in sed
       An  address is either a decimal number that counts input lines cumulatively across files, a '$' character
       that addresses the last line of input, or a context address (which consists of a  BRE,  as  described  in
       Regular Expressions in sed, preceded and followed by a delimiter, usually a <slash>).

       An editing command with no addresses shall select every pattern space.

       An editing command with one address shall select each pattern space that matches the address.

       An  editing command with two addresses shall select the inclusive range from the first pattern space that
       matches the first address through the next pattern space that matches the second. (If the second  address
       is  a  number  less  than  or  equal to the line number first selected, only one line shall be selected.)
       Starting at the first line following the selected range, sed shall look  again  for  the  first  address.
       Thereafter,  the  process  shall  be  repeated.  Omitting either or both of the address components in the
       following form produces undefined results:

           [address[,address]]

   Regular Expressions in sed
       The sed utility shall support the BREs described in the Base Definitions volume of POSIX.1‐2008,  Section
       9.3, Basic Regular Expressions, with the following additions:

        *  In  a  context address, the construction "\cBREc", where c is any character other than <backslash> or
           <newline>, shall be identical to "/BRE/".  If the character  designated  by  c  appears  following  a
           <backslash>,  then it shall be considered to be that literal character, which shall not terminate the
           BRE. For example, in the context address "\xabc\xdefx", the second x stands for itself, so  that  the
           BRE is "abcxdef".

        *  The  escape  sequence '\n' shall match a <newline> embedded in the pattern space. A literal <newline>
           shall not be used in the BRE of a context address or in the substitute function.

        *  If an RE is empty (that is, no pattern is specified) sed shall behave as if the last RE used  in  the
           last command applied (either as an address or as part of a substitute command) was specified.

   Editing Commands in sed
       In  the following list of editing commands, the maximum number of permissible addresses for each function
       is indicated by [0addr], [1addr], or [2addr], representing zero, one, or two addresses.

       The argument text shall consist of one or more lines. Each  embedded  <newline>  in  the  text  shall  be
       preceded  by  a  <backslash>.   Other  <backslash> characters in text shall be removed, and the following
       character shall be treated literally.

       The r and w command verbs, and the w flag to the s command, take an rfile (or wfile) parameter, separated
       from the command verb letter or flag by one or more <blank> characters; implementations  may  allow  zero
       separation as an extension.

       The argument rfile or the argument wfile shall terminate the editing command. Each wfile shall be created
       before  processing  begins. Implementations shall support at least ten wfile arguments in the script; the
       actual number (greater than or equal to 10) that is supported by the implementation is  unspecified.  The
       use  of the wfile parameter shall cause that file to be initially created, if it does not exist, or shall
       replace the contents of an existing file.

       The b, r, s, t, w, y, and : command verbs shall  accept  additional  arguments.  The  following  synopses
       indicate which arguments shall be separated from the command verbs by a single <space>.

       The  a  and  r  commands  schedule  text  for later output. The text specified for the a command, and the
       contents of the file specified for the r command, shall be written to standard  output  just  before  the
       next attempt to fetch a line of input when executing the N or n commands, or when reaching the end of the
       script.  If  written  when  reaching the end of the script, and the −n option was not specified, the text
       shall be written after copying the pattern space to standard output. The contents of the  file  specified
       for  the  r command shall be as of the time the output is written, not the time the r command is applied.
       The text shall be output in the order in which the a and r commands were applied to the input.

       Command verbs other than {, a, b, c, i, r, t, w, :, and # can be  followed  by  a  <semicolon>,  optional
       <blank>  characters,  and another command verb. However, when the s command verb is used with the w flag,
       following it with another command in this manner produces undefined results.

       A function can be preceded by one or more '!'  characters, in which case the function shall be applied if
       the addresses do not select the pattern space. Zero or more <blank> characters shall be  accepted  before
       the  first  '!'  character. It is unspecified whether <blank> characters can follow a '!'  character, and
       conforming applications shall not follow a '!'  character with <blank> characters.

       [2addr] {editing command

       editing command

       ...

       }         Execute a list of sed editing commands only when the pattern space is selected. The list of sed
                 editing commands shall be surrounded by braces  and  separated  by  <newline>  characters,  and
                 conform  to  the following rules. The braces can be preceded or followed by <blank> characters.
                 The editing commands can be preceded by <blank>  characters,  but  shall  not  be  followed  by
                 <blank>  characters.  The <right-brace> shall be preceded by a <newline> and can be preceded or
                 followed by <blank> characters.

       [1addr]a\

       text      Write text to standard output as described previously.

       [2addr]b [label]
                 Branch to the : function bearing the label.  If label is not specified, branch to  the  end  of
                 the  script.  The  implementation  shall  support  labels recognized as unique up to at least 8
                 characters; the actual length (greater than or equal to 8)  that  shall  be  supported  by  the
                 implementation  is  unspecified.  It  is unspecified whether exceeding a label length causes an
                 error or a silent truncation.

       [2addr]c\

       text      Delete the pattern space. With a 0 or 1 address or at the end of a 2-address range, place  text
                 on the output and start the next cycle.

       [2addr]d  Delete the pattern space and start the next cycle.

       [2addr]D  If  the  pattern  space  contains no <newline>, delete the pattern space and start a normal new
                 cycle as if the d command was issued. Otherwise, delete the  initial  segment  of  the  pattern
                 space  through  the  first <newline>, and start the next cycle with the resultant pattern space
                 and without reading any new input.

       [2addr]g  Replace the contents of the pattern space by the contents of the hold space.

       [2addr]G  Append to the pattern space a <newline> followed by the contents of the hold space.

       [2addr]h  Replace the contents of the hold space with the contents of the pattern space.

       [2addr]H  Append to the hold space a <newline> followed by the contents of the pattern space.

       [1addr]i\

       text      Write text to standard output.

       [2addr]l  (The letter ell.) Write the pattern space to standard output in a  visually  unambiguous  form.
                 The  characters  listed  in  the  Base  Definitions  volume  of POSIX.1‐2008, Table 5-1, Escape
                 Sequences and Associated Actions ('\\', '\a', '\b', '\f', '\r', '\t', '\v') shall be written as
                 the corresponding escape sequence; the '\n' in that  table  is  not  applicable.  Non-printable
                 characters not in that table shall be written as one three-digit octal number (with a preceding
                 <backslash>) for each byte in the character (most significant byte first).

                 Long  lines  shall  be  folded,  with  the  point of folding indicated by writing a <backslash>
                 followed by a <newline>; the length at which folding  occurs  is  unspecified,  but  should  be
                 appropriate for the output device. The end of each line shall be marked with a '$'.

       [2addr]n  Write  the  pattern space to standard output if the default output has not been suppressed, and
                 replace the pattern space with the next line of input, less its terminating <newline>.

                 If no next line of input is available, the n command verb shall branch to the end of the script
                 and quit without starting a new cycle.

       [2addr]N  Append the next line of input, less its terminating <newline>, to the pattern space,  using  an
                 embedded  <newline> to separate the appended material from the original material. Note that the
                 current line number changes.

                 If no next line of input is available, the N command verb shall branch to the end of the script
                 and quit without starting a new cycle or copying the pattern space to standard output.

       [2addr]p  Write the pattern space to standard output.

       [2addr]P  Write the pattern space, up to the first <newline>, to standard output.

       [1addr]q  Branch to the end of the script and quit without starting a new cycle.

       [1addr]r rfile
                 Copy the contents of rfile to standard output as described previously. If rfile does not  exist
                 or cannot be read, it shall be treated as if it were an empty file, causing no error condition.

       [2addr]s/BRE/replacement/flags
                 Substitute  the replacement string for instances of the BRE in the pattern space. Any character
                 other than <backslash> or <newline> can be used instead of a <slash> to delimit the BRE and the
                 replacement. Within the BRE and the replacement, the BRE delimiter itself  can  be  used  as  a
                 literal character if it is preceded by a <backslash>.

                 The  replacement  string shall be scanned from beginning to end. An <ampersand> ('&') appearing
                 in the replacement shall be replaced by the string matching the BRE. The special meaning of '&'
                 in this context can be suppressed by preceding it by a <backslash>.  The characters "\n", where
                 n is a digit, shall be replaced  by  the  text  matched  by  the  corresponding  back-reference
                 expression.  If the corresponding back-reference expression does not match, then the characters
                 "\n" shall be replaced by the empty string. The special meaning of "\n" where n is a  digit  in
                 this  context,  can be suppressed by preceding it by a <backslash>.  For each other <backslash>
                 encountered, the following character shall lose its special meaning (if any). The meaning of  a
                 <backslash>  immediately followed by any character other than '&', <backslash>, a digit, or the
                 delimiter character used for this command, is unspecified.

                 A line can be split by substituting a <newline> into  it.  The  application  shall  escape  the
                 <newline>  in  the  replacement  by  preceding  it  by  a <backslash>.  A substitution shall be
                 considered to have been performed even if the replacement string is  identical  to  the  string
                 that  it  replaces. Any <backslash> used to alter the default meaning of a subsequent character
                 shall be discarded from the BRE or the replacement before  evaluating  the  BRE  or  using  the
                 replacement.

                 The value of flags shall be zero or more of:

                 n         Substitute for the nth occurrence only of the BRE found within the pattern space.

                 g         Globally substitute for all non-overlapping instances of the BRE rather than just the
                           first one. If both g and n are specified, the results are unspecified.

                 p         Write the pattern space to standard output if a replacement was made.

                 w wfile   Write.  Append  the  pattern  space  to wfile if a replacement was made. A conforming
                           application shall precede the wfile argument with one or more <blank> characters.  If
                           the  w  flag  is  not  the  last flag value given in a concatenation of multiple flag
                           values, the results are undefined.

       [2addr]t [label]
                 Test. Branch to the : command verb bearing the label if any substitutions have been made  since
                 the  most  recent  reading  of  an  input line or execution of a t.  If label is not specified,
                 branch to the end of the script.

       [2addr]w wfile
                 Append (write) the pattern space to wfile.

       [2addr]x  Exchange the contents of the pattern and hold spaces.

       [2addr]y/string1/string2/
                 Replace all occurrences of characters in string1 with the corresponding characters in  string2.
                 If  a  <backslash> followed by an 'n' appear in string1 or string2, the two characters shall be
                 handled as a single <newline>.  If the number of characters in  string1  and  string2  are  not
                 equal, or if any of the characters in string1 appear more than once, the results are undefined.
                 Any character other than <backslash> or <newline> can be used instead of <slash> to delimit the
                 strings.  If  the delimiter is not 'n', within string1 and string2, the delimiter itself can be
                 used as a literal character if it is preceded by a <backslash>.  If a <backslash> character  is
                 immediately  followed  by  a  <backslash>  character in string1 or string2, the two <backslash>
                 characters shall be counted as a  single  literal  <backslash>  character.  The  meaning  of  a
                 <backslash>  followed  by  any  character  that  is  not  'n',  a <backslash>, or the delimiter
                 character is undefined.

       [0addr]:label
                 Do nothing. This command bears a label to which the b and t commands branch.

       [1addr]=  Write the following to standard output:

                     "%d\n", <current line number>

       [0addr]   Ignore this empty command.

       [0addr]#  Ignore the '#' and the remainder of the line  (treat  them  as  a  comment),  with  the  single
                 exception  that if the first two characters in the script are "#n", the default output shall be
                 suppressed; this shall be the equivalent of specifying −n on the command line.

EXIT STATUS

       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

       Regular expressions match entire strings, not just individual lines, but a <newline> is matched  by  '\n'
       in  a sed RE; a <newline> is not allowed by the general definition of regular expression in POSIX.1‐2008.
       Also note that '\n' cannot be used to match a <newline> at the end of an arbitrary input line;  <newline>
       characters appear in the pattern space as a result of the N editing command.

EXAMPLES

       This sed script simulates the BSD cat −s command, squeezing excess empty lines from standard input.

           sed −n '
           # Write non-empty lines.
           /./ {
               p
               d
               }
           # Write a single empty line, then look for more empty lines.
           /^$/    p
           # Get next line, discard the held <newline> (empty line),
           # and look for more empty lines.
           :Empty
           /^$/    {
               N
               s/.//
               b Empty
               }
           # Write the non-empty line before going back to search
           # for the first in a set of empty lines.
               p
           '

       The following sed command is a much simpler method of squeezing empty lines, although it is not quite the
       same as cat −s since it removes any initial empty lines:

           sed −n '/./,/^$/p'

RATIONALE

       This  volume  of  POSIX.1‐2008 requires implementations to support at least ten distinct wfiles, matching
       historical practice on  many  implementations.  Implementations  are  encouraged  to  support  more,  but
       conforming applications should not exceed this limit.

       The exit status codes specified here are different from those in System V. System V returns 2 for garbled
       sed  commands,  but  returns  zero  with  its usage message or if the input file could not be opened. The
       standard developers considered this to be a bug.

       The manner in which the l command writes non-printable characters was changed  to  avoid  the  historical
       backspace-overstrike  method,  and  other  requirements to achieve unambiguous output were added. See the
       RATIONALE for ed for details of the format chosen, which is the same as that chosen for sed.

       This volume of POSIX.1‐2008 requires implementations to provide pattern and hold spaces of at least  8192
       bytes, larger than the 4000 bytes spaces used by some historical implementations, but less than the 20480
       bytes  limit  used  in  an  early proposal. Implementations are encouraged to allocate dynamically larger
       pattern and hold spaces as needed.

       The requirements for acceptance of <blank> and <space> characters in command lines  has  been  made  more
       explicit  than  in  early  proposals  to describe clearly the historical practice and to remove confusion
       about the phrase ``protect initial blanks [sic] and tabs from the stripping that is done on every  script
       line''  that appears in much of the historical documentation of the sed utility description of text. (Not
       all implementations are known to have stripped <blank> characters from text lines, although they all have
       allowed leading <blank> characters preceding the address on a command line.)

       The treatment of '#' comments differs from the SVID which only allows a comment as the first line of  the
       script,  but  matches  BSD-derived implementations. The comment character is treated as a command, and it
       has  the  same  properties  in  terms  of  being  accepted  with  leading  <blank>  characters;  the  BSD
       implementation has historically supported this.

       Early  proposals  required  that  a  script_file  have  at  least  one  non-comment line. Some historical
       implementations have behaved in unexpected ways if this  were  not  the  case.  The  standard  developers
       considered that this was incorrect behavior and that application developers should not have to avoid this
       feature.  A  correct implementation of this volume of POSIX.1‐2008 shall permit script_files that consist
       only of comment lines.

       Early proposals indicated that if −e and −f options were intermixed, all −e options were processed before
       any −f options. This has been changed  to  process  them  in  the  order  presented  because  it  matches
       historical practice and is more intuitive.

       The  treatment  of  the  p  flag to the s command differs between System V and BSD-based systems when the
       default output is suppressed. In the two examples:

           echo a | sed    's/a/A/p'
           echo a | sed −n 's/a/A/p'

       this volume of POSIX.1‐2008, BSD, System V documentation, and the SVID indicate that  the  first  example
       should  write  two  lines  with A, whereas the second should write one. Some System V systems write the A
       only once in both examples because the p flag is ignored if the −n option is not specified.

       This is a case of a diametrical difference between systems that  could  not  be  reconciled  through  the
       compromise  of declaring the behavior to be unspecified. The SVID/BSD/System V documentation behavior was
       adopted for this volume of POSIX.1‐2008 because:

        *  No known documentation for any historic system describes the interaction between the p flag  and  the
           −n option.

        *  The  selected  behavior  is  more  correct as there is no technical justification for any interaction
           between the p flag and the −n option. A relationship between −n and the p flag might imply that  they
           are  only  used  together,  but  this ignores valid scripts that interrupt the cyclical nature of the
           processing through the use of the D, d, q, or branching commands. Such scripts rely on the  p  suffix
           to  write  the  pattern space because they do not make use of the default output at the ``bottom'' of
           the script.

        *  Because the −n option makes the p flag unnecessary, any interaction  would  only  be  useful  if  sed
           scripts  were written to run both with and without the −n option. This is believed to be unlikely. It
           is even more unlikely that programmers have coded the p flag expecting it to be unnecessary.  Because
           the  interaction  was  not documented, the likelihood of a programmer discovering the interaction and
           depending on it is further decreased.

        *  Finally, scripts that break under the specified behavior produce  too  much  output  instead  of  too
           little, which is easier to diagnose and correct.

       The  form  of  the  substitute  command that uses the n suffix was limited to the first 512 matches in an
       early proposal. This limit has been removed because there is no reason  an  editor  processing  lines  of
       {LINE_MAX}  length  should have this restriction. The command s/a/A/2047 should be able to substitute the
       2047th occurrence of a on a line.

       The b, t, and : commands are documented to ignore leading white space, but no mention is made of trailing
       white space. Historical implementations of sed assigned different locations to the labels 'x'  and  "x ".
       This  is  not useful, and leads to subtle programming errors, but it is historical practice, and changing
       it could theoretically break working scripts. Implementors are encouraged  to  provide  warning  messages
       about labels that are never used or jumps to labels that do not exist.

       Historically, the sed !  and } editing commands did not permit multiple commands on a single line using a
       <semicolon>  as  a  command  delimiter.  Implementations are permitted, but not required, to support this
       extension.

       Earlier versions of this standard allowed for implementations with bytes other than eight bits, but  this
       has been modified in this version.

FUTURE DIRECTIONS

       None.

SEE ALSO

       awk, ed, grep

       The  Base Definitions volume of POSIX.1‐2008, Table 5-1, Escape Sequences and Associated Actions, Chapter
       8, Environment Variables, Section 9.3, Basic Regular Expressions, Section 12.2, Utility Syntax Guidelines

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications  Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc
       and The Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       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 .

IEEE/The Open Group                                   2013                                           SED(1POSIX)