| blob | d14d96acfbe4ad1e9a5d834056bfc40a17ee3c85 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
44 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
45 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
46 .\"
47 .TH COMMAND 1 "Apr 8, 2008"
48 .SH NAME
49 command \- execute a simple command
50 .SH SYNOPSIS
51 .SS "/usr/bin/command"
52 .LP
53 .nf
54 \fBcommand\fR [\fB-p\fR] \fIcommand_name\fR [\fIargument\fR]...
55 .fi
57 .LP
58 .nf
59 \fBcommand\fR [\fB-v\fR | \fB-V\fR] \fIcommand_name\fR
60 .fi
62 .SS "ksh93"
63 .LP
64 .nf
65 \fBcommand\fR [\fB-pvxV\fR] [\fIcommand_name\fR [\fIargument\fR...]]
66 .fi
68 .SH DESCRIPTION
69 .sp
70 .LP
71 The \fBcommand\fR utility causes the shell to treat the arguments as a simple
72 command, suppressing the shell function lookup.
73 .sp
74 .LP
75 If the \fIcommand_name\fR is the same as the name of one of the special
76 built-in utilities, the special properties do not occur. In every other
77 respect, if \fIcommand_name\fR is not the name of a function, the effect of
78 \fBcommand\fR (with no options) are the same as omitting \fBcommand\fR.
79 .sp
80 .LP
81 The \fBcommand\fR utility also provides information concerning how a command
82 name is interpreted by the shell. See \fB-v\fR and \fB-V\fR.
83 .SS "ksh93"
84 .sp
85 .LP
86 Without the \fB-v\fR or \fB-V\fR option, \fBcommand\fR executes
87 \fIcommand_name\fR with arguments specified by \fIargument\fR, suppressing the
88 shell function lookup that normally occurs. In addition, if \fIcommand\fR is a
89 special built-in command, the special properties are removed so that failures
90 do not cause the script that executes it to terminate.
91 .sp
92 .LP
93 If the \fB-v\fR or \fB-V\fR options are specified, \fBcommand\fR is equivalent
94 to \fBwhence\fR(1).
95 .SH OPTIONS
96 .sp
97 .LP
98 The following options are supported by \fB/usr/bin/command\fR:
99 .sp
100 .ne 2
101 .na
102 \fB\fB-p\fR\fR
103 .ad
104 .RS 6n
105 Performs the command search using a default value for \fBPATH\fR that is
106 guaranteed to find all of the standard utilities.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fB-v\fR\fR
113 .ad
114 .RS 6n
115 Writes a string to standard output that indicates the path or command that is
116 be used by the shell, in the current shell execution environment to invoke
117 \fIcommand_name\fR, but does not invoke \fIcommand_name\fR.
118 .RS +4
119 .TP
120 .ie t \(bu
121 .el o
122 Utilities, regular built-in utilities, \fIcommand_names\fR including a slash
123 character, and any implementation-provided functions that are found using the
124 \fBPATH\fR variable is written as absolute path names.
125 .RE
126 .RS +4
127 .TP
128 .ie t \(bu
129 .el o
130 Shell functions, special built-in utilities, regular built-in utilities not
131 associated with a \fBPATH\fR search, and shell reserved words are written as
132 just their names.
133 .RE
134 .RS +4
135 .TP
136 .ie t \(bu
137 .el o
138 An alias is written as a command line that represents its alias definition.
139 .RE
140 .RS +4
141 .TP
142 .ie t \(bu
143 .el o
144 Otherwise, no output is written and the exit status reflects that the name was
145 not found.
146 .RE
147 .RE
149 .sp
150 .ne 2
151 .na
152 \fB\fB-V\fR\fR
153 .ad
154 .RS 6n
155 Writes a string to standard output that indicates how the name specified in the
156 \fIcommand_name\fR operand is interpreted by the shell, in the current shell
157 execution environment, but does not invoke \fIcommand_name\fR. Although the
158 format of this string is unspecified, it indicates in which of the following
159 categories \fIcommand_name\fR falls and include the information stated:
160 .RS +4
161 .TP
162 .ie t \(bu
163 .el o
164 Utilities, regular built-in utilities, and any implementation-provided
165 functions that are found using the \fBPATH\fR variable is identified as such
166 and include the absolute path name in the string.
167 .RE
168 .RS +4
169 .TP
170 .ie t \(bu
171 .el o
172 Other shell functions is identified as functions.
173 .RE
174 .RS +4
175 .TP
176 .ie t \(bu
177 .el o
178 Aliases are identified as aliases and their definitions are included in the
179 string.
180 .RE
181 .RS +4
182 .TP
183 .ie t \(bu
184 .el o
185 Special built-in utilities are identified as special built-in utilities.
186 .RE
187 .RS +4
188 .TP
189 .ie t \(bu
190 .el o
191 Regular built-in utilities not associated with a \fBPATH\fR search is
192 identified as regular built-in utilities.
193 .RE
194 .RS +4
195 .TP
196 .ie t \(bu
197 .el o
198 Shell reserved words are identified as reserved words.
199 .RE
200 .RE
202 .SS "ksh93"
203 .sp
204 .LP
205 The following options are supported by \fBksh93\fR \fBcommand\fR:
206 .sp
207 .ne 2
208 .na
209 \fB\fB-p\fR\fR
210 .ad
211 .RS 6n
212 Causes a default path to be searched rather than the one defined by the value
213 of \fBPATH\fR.
214 .RE
216 .sp
217 .ne 2
218 .na
219 \fB\fB-v\fR\fR
220 .ad
221 .RS 6n
222 Equivalent to:
223 .sp
224 .in +2
225 .nf
226 whence \fIcommand\fR [\fIargument\fR ...]
227 .fi
228 .in -2
229 .sp
231 .RE
233 .sp
234 .ne 2
235 .na
236 \fB\fB-V\fR\fR
237 .ad
238 .RS 6n
239 Equivalent to:
240 .sp
241 .in +2
242 .nf
243 whence -v \fIcommand\fR [\fIargument\fR ...]
244 .fi
245 .in -2
246 .sp
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fB-x\fR\fR
254 .ad
255 .RS 6n
256 If command fails because there are too many arguments, it is invoked multiple
257 times with a subset of the arguments on each invocation. Arguments that occur
258 prior to the first word that expand to multiple arguments and arguments that
259 occur after the last word that expands to multiple arguments are passed on each
260 invocation. The exit status is the maximum invocation exit status.
261 .RE
263 .SH OPERANDS
264 .sp
265 .LP
266 The following operands are supported:
267 .sp
268 .ne 2
269 .na
270 \fB\fIargument\fR\fR
271 .ad
272 .RS 16n
273 One of the strings treated as an argument to \fIcommand_name\fR.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fIcommand_name\fR\fR
280 .ad
281 .RS 16n
282 The name of a utility or a special built-in utility.
283 .RE
285 .SH EXAMPLES
286 .LP
287 \fBExample 1 \fRMaking a Version of \fBcd\fR That Always Prints Out the New
288 Working Directory
289 .sp
290 .LP
291 The following example takes a version of \fBcd\fR that always prints out the
292 new working directory exactly once:
294 .sp
295 .in +2
296 .nf
297 cd() {
298 command cd "$@" >/dev/null
299 pwd
300 }
301 .fi
302 .in -2
303 .sp
305 .LP
306 \fBExample 2 \fRStarting Off a \fBsecure shell script\fR in Which the Script
307 Avoids Being Spoofed by Its Parent
308 .sp
309 .LP
310 The following example starts off a \fBsecure shell script\fR in which the
311 script avoids being spoofed by its parent:
313 .sp
314 .in +2
315 .nf
316 IFS='
317 \&'
318 # The preceding value should be <space><tab><newline>.
319 # Set IFS to its default value.
320 \eunalias -a
321 # Unset all possible aliases.
322 # Note that unalias is escaped to prevent an alias
323 # being used for unalias.
324 unset -f command
325 # Ensure command is not a user function.
326 PATH="$(command -p getconf _CS_PATH):$PATH"
327 # Put on a reliable PATH prefix.
328 # ...
329 .fi
330 .in -2
331 .sp
333 .sp
334 .LP
335 At this point, given correct permissions on the directories called by
336 \fBPATH\fR, the script has the ability to ensure that any utility it calls is
337 the intended one. It is being very cautious because it assumes that
338 implementation extensions can be present that would allow user functions to
339 exist when it is invoked. This capability is not specified by this document,
340 but it is not prohibited as an extension. For example, the \fBENV\fR variable
341 precedes the invocation of the script with a user startup script. Such a script
342 could define functions to spoof the application.
344 .SH ENVIRONMENT VARIABLES
345 .sp
346 .LP
347 See \fBenviron\fR(5) for descriptions of the following environment variables
348 that affect the execution of \fBcommand\fR: \fBLANG\fR, \fBLC_ALL\fR,
349 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
350 .sp
351 .ne 2
352 .na
353 \fB\fBPATH\fR\fR
354 .ad
355 .RS 8n
356 Determine the search path used during the command search, except as described
357 under the \fB-p\fR option.
358 .RE
360 .SH EXIT STATUS
361 .SS "/usr/bin/command"
362 .sp
363 .LP
364 When the \fB-v\fR or \fB-V\fR options are specified, the following exit values
365 are returned:
366 .sp
367 .ne 2
368 .na
369 \fB\fB0\fR\fR
370 .ad
371 .RS 6n
372 Successful completion.
373 .RE
375 .sp
376 .ne 2
377 .na
378 \fB\fB>0\fR\fR
379 .ad
380 .RS 6n
381 The \fIcommand_name\fR could not be found or an error occurred.
382 .RE
384 .sp
385 .LP
386 Otherwise, the following exit values are returned:
387 .sp
388 .ne 2
389 .na
390 \fB\fB126\fR\fR
391 .ad
392 .RS 7n
393 The utility specified by \fIcommand_name\fR was found but could not be invoked.
394 .RE
396 .sp
397 .ne 2
398 .na
399 \fB\fB127\fR\fR
400 .ad
401 .RS 7n
402 An error occurred in the \fBcommand\fR utility or the utility specified by
403 \fIcommand_name\fR could not be found.
404 .RE
406 .sp
407 .LP
408 Otherwise, the exit status of \fBcommand\fR is that of the simple command
409 specified by the arguments to \fBcommand\fR.
410 .SS "ksh93"
411 .sp
412 .LP
413 If \fIcommand\fR is invoked, the exit status of \fBcommand\fR is that of
414 \fIcommand\fR. Otherwise, it is one of the following:
415 .sp
416 .ne 2
417 .na
418 \fB\fB0\fR\fR
419 .ad
420 .RS 7n
421 \fIcommand_name\fR completed successfully.
422 .RE
424 .sp
425 .ne 2
426 .na
427 \fB\fB>0\fR\fR
428 .ad
429 .RS 7n
430 \fB-v\fR or \fB-V\fR has been specified and an error occurred.
431 .RE
433 .sp
434 .ne 2
435 .na
436 \fB\fB126\fR\fR
437 .ad
438 .RS 7n
439 \fIcommand_name\fR was found but could not be invoked.
440 .RE
442 .sp
443 .ne 2
444 .na
445 \fB\fB127\fR\fR
446 .ad
447 .RS 7n
448 \fIcommand_name\fR could not be found.
449 .RE
451 .SH ATTRIBUTES
452 .sp
453 .LP
454 See \fBattributes\fR(5) for descriptions of the following attributes:
455 .SS "/usr/bin/command"
456 .sp
458 .sp
459 .TS
460 box;
461 c | c
462 l | l .
463 ATTRIBUTE TYPE ATTRIBUTE VALUE
464 _
465 Interface Stability Committed
466 _
467 Standard See \fBstandards\fR(5).
468 .TE
470 .SS "ksh93"
471 .sp
473 .sp
474 .TS
475 box;
476 c | c
477 l | l .
478 ATTRIBUTE TYPE ATTRIBUTE VALUE
479 _
480 Interface Stability Uncommitted
481 .TE
483 .SH SEE ALSO
484 .sp
485 .LP
486 \fBksh93\fR(1), \fBsh\fR(1), \fBtype\fR(1), \fBwhence\fR(1),
487 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)