coreutils: General options in join

1 
1 8.3.1 General options
1 ---------------------
1 
11 The program accepts the following options.  Also see ⇒Common
 options.
1 
1 ‘-a FILE-NUMBER’
1      Print a line for each unpairable line in file FILE-NUMBER (either
1      ‘1’ or ‘2’), in addition to the normal output.
1 
1 ‘--check-order’
1      Fail with an error message if either input file is wrongly ordered.
1 
1 ‘--nocheck-order’
1      Do not check that both input files are in sorted order.  This is
1      the default.
1 
1 ‘-e STRING’
1      Replace those output fields that are missing in the input with
1      STRING.  I.e., missing fields specified with the ‘-12jo’ options.
1 
1 ‘--header’
1      Treat the first line of each input file as a header line.  The
1      header lines will be joined and printed as the first output line.
1      If ‘-o’ is used to specify output format, the header line will be
1      printed according to the specified format.  The header lines will
1      not be checked for ordering even if ‘--check-order’ is specified.
1      Also if the header lines from each file do not match, the heading
1      fields from the first file will be used.
1 
1 ‘-i’
1 ‘--ignore-case’
1      Ignore differences in case when comparing keys.  With this option,
1      the lines of the input files must be ordered in the same way.  Use
1      ‘sort -f’ to produce this ordering.
1 
1 ‘-1 FIELD’
1      Join on field FIELD (a positive integer) of file 1.
1 
1 ‘-2 FIELD’
1      Join on field FIELD (a positive integer) of file 2.
1 
1 ‘-j FIELD’
1      Equivalent to ‘-1 FIELD -2 FIELD’.
1 
1 ‘-o FIELD-LIST’
1 ‘-o auto’
1      If the keyword ‘auto’ is specified, infer the output format from
1      the first line in each file.  This is the same as the default
1      output format but also ensures the same number of fields are output
1      for each line.  Missing fields are replaced with the ‘-e’ option
1      and extra fields are discarded.
1 
1      Otherwise, construct each output line according to the format in
1      FIELD-LIST.  Each element in FIELD-LIST is either the single
1      character ‘0’ or has the form M.N where the file number, M, is ‘1’
1      or ‘2’ and N is a positive field number.
1 
1      A field specification of ‘0’ denotes the join field.  In most
1      cases, the functionality of the ‘0’ field spec may be reproduced
1      using the explicit M.N that corresponds to the join field.
1      However, when printing unpairable lines (using either of the ‘-a’
1      or ‘-v’ options), there is no way to specify the join field using
1      M.N in FIELD-LIST if there are unpairable lines in both files.  To
1      give ‘join’ that functionality, POSIX invented the ‘0’ field
1      specification notation.
1 
1      The elements in FIELD-LIST are separated by commas or blanks.
1      Blank separators typically need to be quoted for the shell.  For
1      example, the commands ‘join -o 1.2,2.2’ and ‘join -o '1.2 2.2'’ are
1      equivalent.
1 
1      All output lines—including those printed because of any -a or -v
1      option—are subject to the specified FIELD-LIST.
1 
1 ‘-t CHAR’
1      Use character CHAR as the input and output field separator.  Treat
1      as significant each occurrence of CHAR in the input file.  Use
1      ‘sort -t CHAR’, without the ‘-b’ option of ‘sort’, to produce this
1      ordering.  If ‘join -t ''’ is specified, the whole line is
1      considered, matching the default operation of sort.  If ‘-t '\0'’
1      is specified then the ASCII NUL character is used to delimit the
1      fields.
1 
1 ‘-v FILE-NUMBER’
1      Print a line for each unpairable line in file FILE-NUMBER (either
1      ‘1’ or ‘2’), instead of the normal output.
1 
1 ‘-z’
1 ‘--zero-terminated’
1      Delimit items with a zero byte rather than a newline (ASCII LF).
1      I.e., treat input as items separated by ASCII NUL and terminate
1      output items with ASCII NUL. This option can be useful in
1      conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
1      do the same in order to reliably handle arbitrary file names (even
1      those containing blanks or other special characters).  Note with
1      ‘-z’ the newline character is treated as a field separator.
1 
1    An exit status of zero indicates success, and a nonzero value
1 indicates failure.
1 
1    If the ‘--check-order’ option is given, unsorted inputs will cause a
1 fatal error message.  If the option ‘--nocheck-order’ is given, unsorted
1 inputs will never cause an error message.  If neither of these options
1 is given, wrongly sorted inputs are diagnosed only if an input file is
1 found to contain unpairable lines, and when both input files are non
1 empty.  If an input file is diagnosed as being unsorted, the ‘join’
1 command will exit with a nonzero status (and the output should not be
1 used).
1 
1    Forcing ‘join’ to process wrongly sorted input files containing
1 unpairable lines by specifying ‘--nocheck-order’ is not guaranteed to
1 produce any particular output.  The output will probably not correspond
1 with whatever you hoped it would be.
1