Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Intro(1)							      Intro(1)

       Intro, intro - introduction to commands and application programs

       This  section describes,	in alphabetical	order, commands	available with
       this operating system.

       Pages of	special	interest are categorized as follows:

       1B	Commands found only in the SunOS/BSD Compatibility Package.

       1C	Commands for communicating with	other systems.

       1F	Commands associated with Form and  Menu	 Language  Interpreter

       1S	Commands specific to SunOS.

       See these sections of the  for more information.

	 o  Section 1M in this manual for system maintenance commands.

	 o  Section 4 of this manual for information on	file formats.

	 o  Section  5	of  this manual	for descriptions of publicly available
	    files and miscellaneous information	pages.

	 o  Section 6 in this manual for computer demonstrations.

       For tutorial information	about these commands and procedures, see:


   Manual Page Command Syntax
       Unless otherwise	noted, commands	described in the  section of a	manual
       page accept options and other arguments according to the	following syn-
       tax and should be interpreted as	explained below.

       name [-option...] [cmdarg...] where:

       [ ]	       Surround	an option or cmdarg that is not	required.

       ...	       Indicates multiple occurrences of the option or cmdarg.

       name	       The name	of an executable file.

       { }	       The options and/or arguments enclosed within braces are
		       interdependent,	such  that everything enclosed must be
		       treated as a unit.

       option	       (Always preceded	by a "-".) noargletter... or,  arglet-
		       ter optarg[,...]

       noargletter     A  single  letter representing an option	without	an op-
		       tion-argument. Notice that more	than  one  noargletter
		       option  can  be grouped after one "-" (Guideline	5, be-

       argletter       A single	letter representing an option requiring	an op-

       optarg	       An option-argument (character string) satisfying	a pre-
		       ceding argletter. Notice	that groups of optargs follow-
		       ing  an argletter must be separated by commas, or sepa-
		       rated by	a tab or space character and quoted (Guideline
		       8, below).

       cmdarg	       Path  name  (or	other  command argument) not beginning
		       with "-", or "-"	by itself indicating the standard  in-

       Unless  otherwise specified, whenever an	operand	or option-argument is,
       or contains, a numeric value:

	 o  The	number is interpreted as a decimal integer.

	 o  Numerals in	the range 0 to 2147483647 are syntactically recognized
	    as numeric values.

	 o  When  the utility description states that it accepts negative num-
	    bers as  operands  or  option-arguments,  numerals	in  the	 range
	    -2147483647	 to 2147483647 are syntactically recognized as numeric

	 o  Ranges greater than	those listed here are allowed.

   Command Syntax Standard: Guidelines
       These command syntax guidelines are not followed	by  all	 current  com-
       mands,  but  new	commands are likely to obey them. getopts(1) should be
       used by all shell procedures to	parse  positional  parameters  and  to
       check  for  legal  options.  It supports	Guidelines 3-10	below. The en-
       forcement of the	other guidelines must be done by the command itself.

       1.  Command names (name above) should be	between	two and	 nine  charac-
	   ters	long.

	   Command names should	include	only lower-case	letters	and digits.

       3.  Option names	(option	above) must be one character long.

       4.  All options must be preceded	by "-".

       5.  Options with	no arguments can be grouped after a single "-".

       6.  The	first  option-argument (optarg above) following	an option must
	   be preceded by a tab	or space character.

       7.  Option-arguments cannot be optional.

       8.  Groups of option-arguments following	an option must either be sepa-
	   rated  by  commas or	separated by tab or space character and	quoted
	   (-o xxx,z,yy	or -o"xxx z yy").

       9.  All options must precede operands (cmdarg  above)  on  the  command

       10. "--"	can be used to indicate	the end	of the options.

       11. The order of	the options relative to	one another should not matter.

       12. The	relative order of the operands (cmdarg above) can affect their
	   significance	in ways	determined by the command with which they  ap-

       13. "-" preceded	and followed by	a white	space character	should only be
	   used	to mean	standard input.

       An expanded set of guidelines referred to as CLIP for Command Line  In-
       terface Paradigm	has been developed for Solaris and other Sun products.
       Its intent is to	provide	a command line	syntax	more  closely  aligned
       with  the  GNU command line syntax popular on Linux systems.There is no
       intent to retrofit existing utilities or	even to	apply this to all  new
       utilities. It is	only intended to be applied to sets of utilities being
       developed when appropriate.

       CLIP is a full superset of the guidelines  discussed  above  which  are
       closely aligned with IEEE Std. 1003.1-2001 (SUSv3). It does not include
       all the GNU syntax. The GNU syntax allows constructs that  either  con-
       flict  with  the	 IEEE rules or are ambiguous. These constructs are not

       The expanded CLIP command line syntax is:

       utility_name -a --longopt1 -c option_argument	-f option_argument --longopt2=option_argument	 --longopt3 option_argument operand

       The utility in the example is named utility_name. It is followed	by op-
       tions,  option-arguments, and operands, collectively referred to	as ar-
       guments.	The arguments that consist of a	hyphen followed	a single  let-
       ter  or	digit,	such as	-a, are	known as short-options . The arguments
       that consist of two hyphens followed by a series	of letters, digits and
       hyphens,	 such as --longopt1, are known as long-options . Collectively,
       short-options and long-options are referred to as options (or  histori-
       cally,  flags ).	Certain	options	are followed by	an option-argument, as
       shown with -c option_argument . The arguments following	the  last  op-
       tions  and  option-arguments are	named operands.	Once the first operand
       is encountered, all subsequent arguments	are interpreted	 to  be	 oper-

       Option-arguments	are sometimes shown separated from their short-options
       by <BLANKS>s, sometimes directly	adjacent. This reflects	the  situation
       that in some cases an option-argument is	included within	the same argu-
       ment string as the option; in most cases	it is the next argument.  This
       specification  requires that the	option be a separate argument from its
       option-argument,	but there are some exceptions to ensure	continued  op-
       eration of historical applications:

	 o  If	the  SYNOPSIS of a utility shows a <SPACE> between a short-op-
	    tion and option-argument (as with -c option_argument in the	 exam-
	    ple),  the application uses	separate arguments for that option and
	    its	option-argument.

	 o  If a <SPACE> is not	shown (as with -f option_argument in the exam-
	    ple),  the	application  expects an	option and its option-argument
	    directly adjacent in the same argument string, without intervening

	 o  Notwithstanding  the preceding requirements, an application	should
	    accept short-options and option-arguments as a single argument  or
	    as	separate  arguments  whether  or not a <SPACE> is shown	on the
	    synopsis line.

	 o  Long-options with option-arguments are always documented as	 using
	    an	equals	sign  as the separator between the option name and the
	    option-argument. If	the OPTIONS section  of	 a  utility  shows  an
	    equals  sign (=) between a long-option and its option-argument (as
	    with --longopt2= option_argument in	the  example),	a  application
	    shall  also	 permit	 the use of separate arguments for that	option
	    and	its option-argument (as	with --longopt1	option_argument	in the

       CLIP  expands  the  guidelines  discussed with the following additional

       14.	The form command subcommand [options] [operands] is  appropri-
		ate  for  grouping similar operations. Subcommand names	should
		follow the same	conventions as command names as	 specified  in
		guidelines 1 and 2.

       15.	Long-options  should be	preceded by -- and should include only
		alphanumeric characters	and hyphens from the portable  charac-
		ter  set.  Option names	are typically one to three words long,
		with hyphens to	separate words.

       16.	--name=argument	should be used to specify  an  option-argument
		for a long-option. The form --name argument is also accepted.

       17.	All utilities should support two standard long-options:	--ver-
		sion (with the short-option synonym -V ) and --help (with  the
		short-option  synonym  -?  ).  The  short  option synonyms for
		--version can vary if the preferred synonym is already in  use
		(but a	synonym	shall be provided). Both of these options stop
		further	argument processing when encountered  and  after  dis-
		playing	 the  appropriate output, the utility successfully ex-

       18.	Every short-option should have exactly one corresponding long-
		option	and  every  long-option	should have exactly one	corre-
		sponding short-option. Synonymous options can  be  allowed  in
		the interest of	compatibility with historical practice or com-
		munity versions	of equivalent utilities.

       19.	The short-option name should get its name from the long-option
		name according to these	rules:

		    1.	Use  the  first	letter of the long-option name for the
			short-option name.

		    2.	If the first letter conflicts with other  short-option
			names, choose a	prominent consonant.

		    3.	If  the	 first letter and the prominent	consonant con-
			flict with other shortoption names, choose a prominent

		    4.	If none	of the letters of the long-option name are us-
			able, select an	arbitrary character.

       20.	If a long-option name consists of a single character, it  must
		use  the same character	as the short-option name. Single char-
		acter long-options should be avoided. They  are	 only  allowed
		for the	exceptionally rare case	that a single character	is the
		most  descriptive name.

       21.	The subcommand in the form described in	guideline 1 of the ad-
		ditional  CLIP	guidelines  is generally required. In the case
		where it is omitted, the command shall take  no	 operands  and
		only  options  which are defined to stop further argument pro-
		cessing	when encountered are allowed. Invoking	a  command  of
		this  form  without a subcommand and no	arguments is an	error.
		This guideline is provided to allow the	common	forms  command
		--help,	 command  -?,  command --version, and command -V to be
		accepted in the	command-subcommand construct.

       Several of these	guidelines are only of	interest  to  the  authors  of
       utilities.  They	are provided here for the use of anyone	wanting	to au-
       thor utilities following	this syntax.

       See attributes(5) for a discussion of the  attributes  listed  in  this

       getopts(1), wait(1), exit(2), getopt(3C), wait(3UCB), attributes(5)

       Upon  termination,  each	 command returns two bytes of status, one sup-
       plied by	the system and giving the cause	for termination, and  (in  the
       case  of	 "normal"  termination)	 one  supplied	by  the	 program  [see
       wait(3UCB) and exit(2)].	The former byte	is 0 for  normal  termination.
       The  latter byte	is customarily 0 for successful	execution and non-zero
       to indicate troubles such as erroneous parameters, or bad or inaccessi-
       ble data. It is called variously	"exit code", "exit status", or "return
       code", and is described only where special conventions are involved.

       Some commands produce unexpected	results	when processing	files contain-
       ing  null  characters.  These  commands often treat text	input lines as
       strings and therefore become confused upon encountering a null  charac-
       ter (the	string terminator) within a line.

				  28 Sep 2005			      Intro(1)


Want to link to this manual page? Use this URL:

home | help