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