[unix-history] / usr / src / usr.bin / join / join.1

.TH JOIN 1L \" -*- nroff -*-
.SH NAME
join \- join lines of two files on a common field
.SH SYNOPSIS
.B join
[\-a 1|2] [\-v 1|2] [\-e empty-string] [\-o field-list...] [\-t char]
[\-j[1|2] field] [\-1 field] [\-2 field] file1 file2
.SH DESCRIPTION
This manual page
documents the GNU version of
.BR join .
.B join
prints to the standard output a line for each pair of input lines, one
each from
.I file1
and
.IR file2 ,
that have identical join fields.  Either filename (but not both) can
be `\-', meaning the standard input.
.I file1
and
.I file2
should be already sorted in increasing order (not numerically) on the
join fields; unless the
.I \-t
option is given, they should be sorted ignoring blanks at the start of
the line, as
.B sort
does when given the
.I \-b
option.
.PP
The defaults are: the join field is the first field in each line;
fields in the input are separated by one or more blanks, with leading
blanks on the line ignored; fields in the output are separated by a
space; each output line consists of the join field, the remaining
fields from
.IR file1 ,
then the remaining fields from
.IR file2 .
.SS OPTIONS
.TP
.I "\-a file-number"
Print a line for each unpairable line in file
.I file-number
(either 1 or 2), in addition to the normal output.
.TP
.I "\-e string"
Replace empty output fields (those that are missing in the input) with
.IR string .
.TP
.I "\-1, \-j1 field"
Join on field
.I field
(a positive integer) of file 1.
.TP
.I "\-2, \-j2 field"
Join on field
.I field
(a positive integer) of file 2.
.TP
.I "\-j field"
Equivalent to
.IR "\-1 field \-2 field" .
.TP
.I "\-o field-list..."
Construct each output line according to the format in
.IR field-list .
Each element in
.I field-list
consists of a file number (either 1 or 2), a period, and a field
number (a positive integer).  The elements in the list are separated
by commas or blanks.  Multiple
.I field-list
arguments can be given after a single
.I \-o
option; the values of all lists given with
.I \-o
are concatenated together.
.TP
.I "\-t char"
Use character
.I char
as the input and output field separator.
.TP
.I "\-v file-number"
Print a line for each unpairable line in file
.I file-number
(either 1 or 2), instead of the normal output.
.PP
The long-named options can be introduced with `+' as well as `\-\-',
for compatibility with previous releases.  Eventually support for `+'
will be removed, because it is incompatible with the POSIX.2 standard.
Commit	Line	Data
5824a9c7 WJ	1	.TH JOIN 1L \" -- nroff --
	2	.SH NAME
	3	join \- join lines of two files on a common field
	4	.SH SYNOPSIS
	5	.B join
	6	[\-a 1\|2] [\-v 1\|2] [\-e empty-string] [\-o field-list...] [\-t char]
	7	[\-j[1\|2] field] [\-1 field] [\-2 field] file1 file2
	8	.SH DESCRIPTION
	9	This manual page
	10	documents the GNU version of
	11	.BR join .
	12	.B join
	13	prints to the standard output a line for each pair of input lines, one
	14	each from
	15	.I file1
	16	and
	17	.IR file2 ,
	18	that have identical join fields. Either filename (but not both) can
	19	be `\-', meaning the standard input.
	20	.I file1
	21	and
	22	.I file2
	23	should be already sorted in increasing order (not numerically) on the
	24	join fields; unless the
	25	.I \-t
	26	option is given, they should be sorted ignoring blanks at the start of
	27	the line, as
	28	.B sort
	29	does when given the
	30	.I \-b
	31	option.
	32	.PP
	33	The defaults are: the join field is the first field in each line;
	34	fields in the input are separated by one or more blanks, with leading
	35	blanks on the line ignored; fields in the output are separated by a
	36	space; each output line consists of the join field, the remaining
	37	fields from
	38	.IR file1 ,
	39	then the remaining fields from
	40	.IR file2 .
	41	.SS OPTIONS
	42	.TP
	43	.I "\-a file-number"
	44	Print a line for each unpairable line in file
	45	.I file-number
	46	(either 1 or 2), in addition to the normal output.
	47	.TP
	48	.I "\-e string"
	49	Replace empty output fields (those that are missing in the input) with
	50	.IR string .
	51	.TP
	52	.I "\-1, \-j1 field"
	53	Join on field
	54	.I field
	55	(a positive integer) of file 1.
	56	.TP
	57	.I "\-2, \-j2 field"
	58	Join on field
	59	.I field
	60	(a positive integer) of file 2.
	61	.TP
	62	.I "\-j field"
	63	Equivalent to
	64	.IR "\-1 field \-2 field" .
65	.TP
66	.I "\-o field-list..."
67	Construct each output line according to the format in
68	.IR field-list .
69	Each element in
70	.I field-list
71	consists of a file number (either 1 or 2), a period, and a field
72	number (a positive integer). The elements in the list are separated
73	by commas or blanks. Multiple
74	.I field-list
75	arguments can be given after a single
76	.I \-o
77	option; the values of all lists given with
78	.I \-o
79	are concatenated together.
80	.TP
81	.I "\-t char"
82	Use character
83	.I char
84	as the input and output field separator.
85	.TP
86	.I "\-v file-number"
87	Print a line for each unpairable line in file
88	.I file-number
89	(either 1 or 2), instead of the normal output.
90	.PP
91	The long-named options can be introduced with `+' as well as `\-\-',
92	for compatibility with previous releases. Eventually support for `+'
93	will be removed, because it is incompatible with the POSIX.2 standard.