join.1 - sbase - suckless unix tools
 (HTM) git clone git://git.suckless.org/sbase
 (DIR) Log
 (DIR) Files
 (DIR) Refs
 (DIR) README
 (DIR) LICENSE
       ---
       join.1 (2129B)
       ---
            1 .Dd October 8, 2015
            2 .Dt JOIN 1
            3 .Os sbase
            4 .Sh NAME
            5 .Nm join
            6 .Nd relational database operator
            7 .Sh SYNOPSIS
            8 .Nm
            9 .Op Fl 1 Ar field
           10 .Op Fl 2 Ar field
           11 .Op Fl o Ar list
           12 .Op Fl e Ar string
           13 .Op Fl a Ar fileno | Fl v Ar fileno
           14 .Op Fl t Ar delim
           15 .Ar file1 file2
           16 .Sh DESCRIPTION
           17 .Nm
           18 lines from
           19 .Ar file1
           20 and
           21 .Ar file2
           22 on a matching field.
           23 If one of the input files is '-', standard input is read for that file.
           24 .Pp
           25 Files are read sequentially and are assumed to be sorted on the join
           26 field.
           27 .Nm
           28 does not check the order of input, and joining two unsorted files will
           29 produce unexpected output.
           30 .Pp
           31 By default, input lines are matched on the first blank-separated
           32 field; output lines are space-separated and consist of the join field
           33 followed by the remaining fields from
           34 .Ar file1 ,
           35 then the remaining fields from
           36 .Ar file2 .
           37 .Sh OPTIONS
           38 .Bl -tag -width Ds
           39 .It Fl 1 Ar field
           40 Join on the
           41 .Ar field Ns th
           42 field of file 1.
           43 .It Fl 2 Ar field
           44 Join on the
           45 .Ar field Ns th
           46 field of file 2.
           47 .It Fl a Ar fileno
           48 Print unpairable lines from file
           49 .Ar fileno
           50 in addition to normal output.
           51 .It Fl e Ar string
           52 When used with
           53 .Fl o ,
           54 replace empty fields in the output list with
           55 .Ar string .
           56 .It Fl o Ar list
           57 Format output according to the string
           58 .Ar list .
           59 Each element of
           60 .Ar list
           61 may be either
           62 .Ar fileno.field
           63 or 0 (representing the join field).
           64 Elements in
           65 .Ar list
           66 may be separated by blanks or commas.
           67 For example,
           68 .Bd -literal -offset indent
           69 join -o "0 2.1 1.3"
           70 .Ed
           71 .Pp
           72 would print the join field, the first field of
           73 .Ar file2 ,
           74 then the third field of
           75 .Ar file1 .
           76 .Pp
           77 Only paired lines are formatted with the
           78 .Fl o
           79 option.
           80 Unpairable lines (selected with
           81 .Fl a
           82 or
           83 .Fl v )
           84 are printed raw.
           85 .It Fl t Ar delim
           86 Use the arbitrary string
           87 .Ar delim
           88 as field delimiter for both input and output.
           89 .It Fl v Ar fileno
           90 Print unpairable lines from file
           91 .Ar fileno
           92 instead of normal output.
           93 .El
           94 .Sh STANDARDS
           95 POSIX.1-2013.
           96 .Pp
           97 With the following exception:
           98 .Bl -bullet -offset indent
           99 .It
          100 Unpairable lines ignore formatting specified with
          101 .Fl o .
          102 .El
          103 .Pp
          104 The possibility of specifying multibyte delimiters of arbitrary
          105 length is an extension to the specification.