1.\" $NetBSD: apply.1,v 1.15 2016/03/14 09:53:37 wiz Exp $ 2.\" 3.\" Copyright (c) 1983, 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)apply.1 8.2 (Berkeley) 4/4/94 31.\" 32.Dd March 12, 2016 33.Dt APPLY 1 34.Os 35.Sh NAME 36.Nm apply 37.Nd apply a command to a list of arguments 38.Sh SYNOPSIS 39.Nm 40.Op Fl a Ns Ar c 41.Op Fl Ns Ar # 42.Ar command arguments ... 43.Sh DESCRIPTION 44.Nm 45divides its 46.Ar arguments 47into fixed-size groups and runs 48.Ar command 49in turn on each group. 50.Pp 51On each execution of 52.Ar command , 53each character sequence of the form 54.Dq Li \&%d 55in 56.Ar command , 57where 58.Ar d 59is a digit from 1 to 9, is replaced with the 60.Ar d Ns \'th 61argument from the current argument group. 62The argument group size is set to the largest such 63.Ar d 64found. 65Any given argument number can be used arbitrarily many times. 66(Including zero.) 67.Pp 68If no explicit substitution sequences are found in 69.Ar command , 70the current argument group is substituted after 71.Ar command 72delimited by spaces, and the argument group size defaults to 1 and can 73be set with the 74.Fl # 75option. 76.Pp 77If the argument group size is set to 0, one argument from 78.Ar arguments 79is taken for each execution of 80.Ar command 81anyway, but is discarded and not substituted; thus, 82.Ar command 83is run verbatim once for every argument. 84.Pp 85The options are as follows: 86.Bl -tag -width "-ac" 87.It Fl Ns Ar # 88Set the argument group size. 89Ignored if explicit substitutions are used. 90.It Fl a Ns Ar c 91Change the magic substitution character from the default 92.Dq Li % 93to 94.Ar c . 95.El 96.Sh ENVIRONMENT 97The following environment variable affects the execution of 98.Nm : 99.Bl -tag -width SHELL 100.It Ev SHELL 101Pathname of the shell to use to execute 102.Ar command . 103If this variable is not defined, the Bourne shell is used. 104.El 105.Sh FILES 106.Bl -tag -width /bin/sh -compact 107.It Pa /bin/sh 108Default shell. 109.El 110.Sh EXAMPLES 111.Bl -tag -width apply -compact 112.It Li "apply echo *" 113Prints the name of every file in the current directory. 114.It Li "apply \-2 diff a1 b1 a2 b2 a3 b3" 115Compares the `a' files to the `b' files. 116.It Li "apply \-0 who 1 2 3 4 5" 117Runs 118.Xr who 1 1195 times. 120.It Li "apply \'ln %1 /home/joe/joe.%1\'" * 121Hard-links all files in the current directory into the directory 122.Pa /home/joe , 123with their names prefixed with "joe.". 124.It Li "apply \'cvs diff %1 > %1.diff'" *.c 125Diff all C sources in the current directory against the last 126checked-in version and store each result in its own output file. 127.El 128.Sh HISTORY 129The 130.Nm 131command appeared in 132.Bx 4.2 . 133.Sh AUTHORS 134.An Rob Pike 135.Sh RESTRICTIONS 136The complete command to be executed on each iteration is assembled as 137a string without additional quoting and then passed to a copy of the 138shell for parsing and execution. 139Thus, commands or arguments that contain spaces or shell 140metacharacters may behave in unexpected ways. 141.Pp 142To protect a shell metacharacter fully it must be quoted twice, once 143against the current shell and once against the subshell used for 144execution. 145Similarly, for a shell metacharacter to be interpreted by the subshell 146it must be quoted to protect it from the current shell. 147A simple rule of thumb is to enclose the entire 148.Ar command 149in single quotes 150.Pq '' 151so that the current shell does not interpret any of it. 152.Sh BUGS 153There is no easy way to produce the literal string 154.Dq %1 155in 156.Ar command . 157.Pp 158.Nm 159unconditionally inserts "exec" at the beginning of each copy of 160.Ar command 161so compound commands may not behave as intended. 162