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
		       option-argument.	 Notice	that more than one noargletter
		       option can be  grouped  after  one  "-"	(Guideline  5,

       argletter       A  single  letter  representing	an option requiring an

       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

       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
       enforcement 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

       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
       Interface Paradigm has been developed for Solaris and other  Sun	 prod-
       ucts.  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	utili-
       ties 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
       options,	option-arguments, and operands,	collectively  referred	to  as
       arguments.  The	arguments  that	 consist of a hyphen followed a	single
       letter 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
       options 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
       operation of historical applications:

	 o  If the SYNOPSIS of a utility shows	a  <SPACE>  between  a	short-
	    option  and	 option-argument  (as  with  -c	option_argument	in the
	    example), 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

       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
			usable,	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
		additional  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
       author 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