home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 3 / 3884 / apply.1 next >
Encoding:
Text File  |  1991-08-22  |  3.1 KB  |  156 lines
  1. ..TH APPLY 1V VMB
  2. '\"    last edit:    85/10/20    D A Gwyn
  3. '\"    SCCS ID:    @(#)apply.1    1.1
  4. ..SH NAME
  5. apply \- apply a command to a set of arguments
  6. ..SH SYNOPSIS
  7. ..B apply
  8. [
  9. ..BR \-a c
  10. ] [ \-n ] [
  11. ..B \-v
  12. ] [
  13. ..B \-w
  14. ] command args ...
  15. ..SH DESCRIPTION
  16. ..I Apply\^
  17. runs the named
  18. ..I command\^
  19. on successive batches of arguments
  20. taken from
  21. ..I args\^
  22. until they are all consumed.
  23. The optional number
  24. ..I n\^
  25. specifies the number of arguments per batch
  26. (default 1);
  27. this many arguments
  28. (separated by spaces)
  29. are appended to
  30. ..I command\^
  31. each time it is run.
  32. In the special case that
  33. ..I n\^
  34. is zero,
  35. ..I command\^
  36. is run without arguments
  37. once for each
  38. ..IR arg\^ .
  39. ..P
  40. However, if
  41. ..I command\^
  42. contains any character sequence
  43. consisting of the character
  44. ..I c\^
  45. (default
  46. ..BR % )
  47. followed by a digit
  48. ..I d\^
  49. from 1 through 9,
  50. ..I n\^
  51. is ignored and each such
  52. ..I cd\^
  53. pair is replaced by the
  54. ..IR d\^ th
  55. following unconsumed
  56. ..IR arg\^ .
  57. In this case, the maximum such digit
  58. ..I d\^
  59. in
  60. ..I command\^
  61. specifies the number of
  62. ..I args\^
  63. consumed per batch.
  64. ..P
  65. The
  66. ..B \-v
  67. (``verbose'') option
  68. causes
  69. ..I apply\^
  70. to print each constructed command
  71. before it is run.
  72. The
  73. ..B \-w
  74. option causes
  75. a warning to be printed for any command that
  76. returns a non-zero exit status.
  77. ..SH CAVEATS
  78. The constructed command
  79. is executed by
  80. ..IR system\^ (3S),
  81. so watch out for shell metacharacters in
  82. ..I command\^
  83. or
  84. ..IR args\^ .
  85. It is best to enclose complicated commands in single quotes \'\ \',
  86. to prevent immediate interpretation by the current shell process.
  87. ..P
  88. It is necessary to choose an alternate
  89. substitution prefix character
  90. ..IR c\^ ,
  91. if the default
  92. ..B %
  93. character must appear literally
  94. followed by a positive digit
  95. in the constructed command.
  96. ..SH EXAMPLES
  97. The following shell command
  98. inefficiently emulates the behavior of `ls':
  99. ..RS
  100. $ \|\fIapply \|echo \|*\fP
  101. ..RE
  102. ..P
  103. The following shell command
  104. compares the `a' files against the corresponding `b' files:
  105. ..RS
  106. $ \|\fIapply \|\-2 \|cmp \|a1 \|b1 \|a2 \|b2 \|...\fP
  107. ..RE
  108. ..P
  109. The following shell command
  110. runs
  111. ..IR date\^ (1)
  112. 20 times; like
  113. `for i in \`seq 20\`; do date; done':
  114. ..RS
  115. $ \|\fIapply \|\-0 \|date \|\`seq \|20\`\fP
  116. ..RE
  117. ..P
  118. The following shell command
  119. exchanges the names of the `a' files with the corresponding `b' files:
  120. ..RS
  121. $ \|\fIapply \|\'mv \|%1 \|t; mv \|%2 \|%1; mv \|t \|%2\' \|a1 \|b1 \|a2 \|b2 \|...\fP
  122. ..RE
  123. ..SH "SEE ALSO"
  124. find(1), pick(1V), sh(1).
  125. ..SH DIAGNOSTICS
  126. Error messages,
  127. as well as requested
  128. verbose or warning messages,
  129. are printed on the standard error output
  130. and are meant to be self-explanatory.
  131. ``Command too long''
  132. indicates that the result of adding arguments to the
  133. ..I command\^
  134. would exceed some system limit
  135. on the total length of a command line.
  136. ..RI `` N\^
  137. args left over''
  138. indicates that the number of
  139. arguments per batch
  140. did not exactly divide
  141. the number of supplied
  142. ..IR args\^ .
  143. ..SH "EXIT CODES"
  144. If all applications of
  145. ..I command\^
  146. return zero exit status,
  147. then so will
  148. ..IR apply\^ .
  149. An exit status of
  150. 1 is returned if any
  151. ..I command\^
  152. execution errors occur;
  153. 2 is returned for usage errors.
  154. ..SH AUTHOR
  155. Douglas A. Gwyn, BRL/VLD-VMB (inspired by 8th Edition UNIX)
  156.