Unix/Linux Go Back    


Linux 2.6 - man page for command (linux section 1posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


COMMAND(P)			    POSIX Programmer's Manual			       COMMAND(P)

NAME
       command - execute a simple command

SYNOPSIS
       command [-p] command_name [argument ...]

       command [ -v | -V ] command_name

DESCRIPTION
       The command utility shall cause the shell to treat the arguments as a simple command, sup-
       pressing the shell function lookup that is described in Command	Search	and  Execution	,
       item 1b.

       If  the command_name is the same as the name of one of the special built-in utilities, the
       special properties in the enumerated list at the beginning of Special  Built-In	Utilities
       shall  not  occur.  In every other respect, if command_name is not the name of a function,
       the effect of command (with no options) shall be the same as omitting command.

       On systems supporting the User Portability Utilities  option,  the  command  utility  also
       shall  provide  information concerning how a command name is interpreted by the shell; see
       -v and -V.

OPTIONS
       The command utility shall conform to the Base Definitions volume of  IEEE Std 1003.1-2001,
       Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported:

       -p     Perform  the  command  search  using a default value for PATH that is guaranteed to
	      find all of the standard utilities.

       -v     (On systems supporting the User Portability Utilities option.) Write  a  string  to
	      standard	output	that  indicates  the pathname or command that will be used by the
	      shell, in the current shell execution environment (see Shell Execution  Environment
	      ), to invoke command_name, but do not invoke command_name.

	       * Utilities,  regular  built-in utilities, command_names including a slash charac-
		 ter, and any implementation-defined functions that  are  found  using	the  PATH
		 variable  (as	described  in Command Search and Execution ), shall be written as
		 absolute pathnames.

	       * Shell functions, special built-in  utilities,	regular  built-in  utilities  not
		 associated with a PATH search, and shell reserved words shall be written as just
		 their names.

	       * An alias shall be written as a command line that represents  its  alias  defini-
		 tion.

	       * Otherwise, no output shall be written and the exit status shall reflect that the
		 name was not found.

       -V     (On systems supporting the User Portability Utilities option.) Write  a  string  to
	      standard	output that indicates how the name given in the command_name operand will
	      be interpreted by the shell, in the current shell execution environment (see  Shell
	      Execution  Environment  ),  but  do not invoke command_name. Although the format of
	      this string is unspecified, it shall indicate in which of the following  categories
	      command_name falls and shall include the information stated:

	       * Utilities,  regular built-in utilities, and any implementation-defined functions
		 that are found using the PATH variable (as described in Command Search and  Exe-
		 cution  ),  shall be identified as such and include the absolute pathname in the
		 string.

	       * Other shell functions shall be identified as functions.

	       * Aliases shall be identified as aliases and their  definitions	included  in  the
		 string.

	       * Special built-in utilities shall be identified as special built-in utilities.

	       * Regular built-in utilities not associated with a PATH search shall be identified
		 as regular built-in utilities. (The term "regular" need not be used.)

	       * Shell reserved words shall be identified as reserved words.

OPERANDS
       The following operands shall be supported:

       argument
	      One of the strings treated as an argument to command_name.

       command_name

	      The name of a utility or a special built-in utility.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of command:

       LANG   Provide a default value for the internationalization variables that  are	unset  or
	      null. (See the Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Inter-
	      nationalization Variables for the precedence of internationalization variables used
	      to determine the values of locale categories.)

       LC_ALL If  set  to a non-empty string value, override the values of all the other interna-
	      tionalization variables.

       LC_CTYPE
	      Determine the locale for the interpretation of sequences of bytes of text  data  as
	      characters  (for	example, single-byte as opposed to multi-byte characters in argu-
	      ments).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic messages written to standard error and informative messages written to stan-
	      dard output.

       NLSPATH
	      Determine the location of message catalogs for the processing of LC_MESSAGES .

       PATH   Determine the search path used during  the  command  search  described  in  Command
	      Search and Execution , except as described under the -p option.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       When the -v option is specified, standard output shall be formatted as:

	      "%s\n", <pathname or command>

       When the -V option is specified, standard output shall be formatted as:

	      "%s\n", <unspecified>

STDERR
       The standard error shall be used only for diagnostic messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       When the -v or -V options are specified, the following exit values shall be returned:

	0     Successful completion.

       >0     The command_name could not be found or an error occurred.

       Otherwise, the following exit values shall be returned:

       126    The utility specified by command_name was found but could not be invoked.

       127    An  error  occurred in the command utility or the utility specified by command_name
	      could not be found.

       Otherwise, the exit status of command shall be that of the simple command specified by the
       arguments to command.

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       The  order  for	command  search  allows  functions to override regular built-ins and path
       searches. This utility is necessary to allow functions that have the same name as a  util-
       ity to call the utility (instead of a recursive call to the function).

       The  system  default  path  is available using getconf; however, since getconf may need to
       have the PATH set up before it can be called itself, the following can be used:

	      command -p getconf _CS_PATH

       There are some advantages to suppressing the special characteristics of special	built-ins
       on occasion. For example:

	      command exec > unwritable-file

       does not cause a non-interactive script to abort, so that the output status can be checked
       by the script.

       The command, env, nohup, time, and xargs utilities have been specified to  use  exit  code
       127  if	an  error occurs so that applications can distinguish "failure to find a utility"
       from "invoked utility exited with an error indication". The value 127 was  chosen  because
       it  is  not  commonly used for other meanings; most utilities use small values for "normal
       error conditions" and the values above 128 can be confused with termination due to receipt
       of  a  signal.	The value 126 was chosen in a similar manner to indicate that the utility
       could be found, but not invoked. Some scripts produce meaningful error messages	differen-
       tiating	the 126 and 127 cases. The distinction between exit codes 126 and 127 is based on
       KornShell practice that uses 127 when all attempts to exec the utility fail with [ENOENT],
       and uses 126 when any attempt to exec the utility fails for any other reason.

       Since  the  -v  and  -V options of command produce output in relation to the current shell
       execution environment, command is generally provided as a shell regular built-in. If it is
       called in a subshell or separate utility execution environment, such as one of the follow-
       ing:

	      (PATH=foo command -v)
	       nohup command -v

       it does not necessarily produce correct results. For example, when called with nohup or an
       exec  function,	in a separate utility execution environment, most implementations are not
       able to identify aliases, functions, or special built-ins.

       Two types of regular built-ins could be encountered on a system and  these  are	described
       separately  by  command. The description of command search in Command Search and Execution
       allows for a standard utility to be implemented as a regular built-in as  long  as  it  is
       found  in  the appropriate place in a PATH search.  So, for example, command -v true might
       yield /bin/true or some similar pathname. Other implementation-defined utilities that  are
       not  defined by this volume of IEEE Std 1003.1-2001 might exist only as built-ins and have
       no pathname associated with them. These produce output identified as (regular)  built-ins.
       Applications  encountering  these  are  not able to count on execing them, using them with
       nohup, overriding them with a different PATH , and so on.

EXAMPLES
	1. Make a version of cd that always prints out the new working directory exactly once:

	   cd() {
	       command cd "$@" >/dev/null
	       pwd
	   }

	2. Start off a "secure shell script" in which the script avoids being spoofed by its par-
	   ent:

	   IFS='
	   #	The preceding value should be <space><tab><newline>.
	   #	Set IFS to its default value.

	   \unalias -a
	   #	Unset all possible aliases.
	   #	Note that unalias is escaped to prevent an alias
	   #	being used for unalias.

	   unset -f command
	   #	Ensure command is not a user function.

	   PATH="$(command -p getconf _CS_PATH):$PATH"
	   #	Put on a reliable PATH prefix.

	   #	...

       At  this  point,  given correct permissions on the directories called by PATH , the script
       has the ability to ensure that any utility it calls is the intended one. It is being  very
       cautious because it assumes that implementation extensions may be present that would allow
       user functions to exist when it is invoked; this capability is not specified by this  vol-
       ume  of	IEEE Std 1003.1-2001, but it is not prohibited as an extension.  For example, the
       ENV variable precedes the invocation of the script with a user  start-up  script.  Such	a
       script could define functions to spoof the application.

RATIONALE
       Since command is a regular built-in utility it is always found prior to the PATH search.

       There is nothing in the description of command that implies the command line is parsed any
       differently from that of any other simple command. For example:

	      command a | b ; c

       is not parsed in any special way that causes '|' or ';' to be treated other  than  a  pipe
       operator or semicolon or that prevents function lookup on b or c.

       The  command  utility is somewhat similar to the Eighth Edition shell builtin command, but
       since command also goes to the file system to search for utilities, the name builtin would
       not be intuitive.

       The  command utility is most likely to be provided as a regular built-in. It is not listed
       as a special built-in for the following reasons:

	* The removal of exportable functions made the special precedence of a	special  built-in
	  unnecessary.

	* A  special  built-in has special properties (see Special Built-In Utilities ) that were
	  inappropriate for invoking other utilities. For example, two commands such as:

	  date > unwritable-file

	  command date > unwritable-file

       would have entirely different results; in a non-interactive script, the former would  con-
       tinue  to execute the next command, the latter would abort. Introducing this semantic dif-
       ference along with suppressing functions was seen to be non-intuitive.

       The -p option is present because it is useful to be able to ensure a safe path search that
       finds  all  the	standard  utilities.  This  search might not be identical to the one that
       occurs through one of the exec functions (as defined in the System  Interfaces  volume  of
       IEEE Std 1003.1-2001)  when  PATH is unset. At the very least, this feature is required to
       allow the script to access the correct version of getconf so that the value of the default
       path can be accurately retrieved.

       The  command -v and -V options were added to satisfy requirements from users that are cur-
       rently accomplished by three different historical utilities: type in the System	V  shell,
       whence  in the KornShell, and which in the C shell. Since there is no historical agreement
       on how and what to accomplish here, the POSIX command utility was enhanced and the histor-
       ical  utilities were left unmodified. The C shell which merely conducts a path search. The
       KornShell whence is more elaborate-in addition to the categories  required  by  POSIX,  it
       also reports on tracked aliases, exported aliases, and undefined functions.

       The output format of -V was left mostly unspecified because human users are its only audi-
       ence. Applications should not be written to care about this information; they can use  the
       output of -v to differentiate between various types of commands, but the additional infor-
       mation that may be emitted by the more verbose -V is not needed and should  not	be  arbi-
       trarily constrained in its verbosity or localization for application parsing reasons.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Command	Search and Execution , Shell Execution Environment , Special Built-In Utilities ,
       sh , type , the System Interfaces volume of IEEE Std 1003.1-2001, exec

COPYRIGHT
       Portions of this text are reprinted and	reproduced  in	electronic  form  from	IEEE  Std
       1003.1,	2003  Edition,	Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003  by
       the  Institute  of  Electrical  and  Electronics Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				       COMMAND(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:59 AM.