[apple/system_cmds.git] / arch.tproj / arch.1

.\" Copyright (c) 1994 SigmaSoft, Th. Lockert
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed by SigmaSoft, Th. Lockert.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\"	$OpenBSD: arch.1,v 1.2 1996/06/29 20:29:34 tholo Exp $
.\"
.\" Modifications made 8/20/97 (c) Apple Computer, Inc.
.\" Modifications made 11/12/06 (c) Apple Computer, Inc.

.Dd July 8, 2010
.Dt ARCH 1
.Os "Mac OS X"
.Sh NAME
.Nm arch
.Nd print architecture type or run selected architecture of a universal binary
.Sh SYNOPSIS
.Nm arch
.Nm arch
.Op Fl 32
.Op Fl 64
.Oo
.Oo Fl Ns Ar arch_name | Fl arch Ar arch_name Oc Ns ...
.Oc
.Op Fl c
.Oo Fl d Ar envname Oc Ns ...
.Oo Fl e Ar envname=value Oc Ns ...
.Op Fl h
.Ar prog
.Op Ar args No ...
.Sh DESCRIPTION
The
.Nm arch
command with no arguments, displays the machine's architecture type.
.Pp
The other use of the
.Nm arch
command is to run a selected architecture of a universal binary.
A universal binary contains code that can run on different architectures.
By default, the operating system will select the architecture that most closely
matches the processor type.
A 64-bit architecture is preferred over a 32-bit architecture on a 64-bit
processor, while only 32-bit architectures can run on a 32-bit processor.
.Pp
When the most natural architecture is unavailable, the operating system will
try to pick another architecture.
On 64-bit processors, a 32-bit architecture is tried.
Otherwise, no architecture is run, and an error results.
.Pp
The
.Nm arch
command can be used to alter the operating system's normal selection order.
The most common use is to select the 32-bit architecture on a 64-bit processor,
even if a 64-bit architecture is available.
.Pp
The
.Ar arch_name
argument must be one of the currently supported architectures:
.Bl -tag -width x86_64h -offset indent
.It i386
32-bit intel
.It x86_64
64-bit intel
.It x86_64h
64-bit intel (haswell)
.It arm64
64-bit arm
.It arm64e
64-bit arm (Apple Silicon)
.El
.Pp
If the binary does not contain code for
.Ar arch_name ,
the
.Nm arch
command may try to select a close match. If arm64 is specified and not found,
arm64e will be tried next. If this happens, the order the architectures will
be tried is not guaranteed.
.Pp
Either prefix the architecture with a hyphen, or (for compatibility with
other commands), use
.Fl arch
followed by the architecture.
.Pp
If more than one architecture is specified, the operating system will try each
one in order, skipping an architecture that is not supported on the current
processor, or is unavailable in the universal binary.
.Pp
The other options are:
.Bl -tag -width ".Fl e Ar envname=value"
.It Fl 32
Add the native 32-bit architecture to the list of architectures.
.It Fl 64
Add the native 64-bit architecture to the list of architectures.
.It Fl c
Clears the environment that will be passed to the command to be run.
.It Fl d Ar envname
Deletes the named environment variable from the environment that will be passed
to the command to be run.
.It Fl e Ar envname=value
Assigns the given value to the named environment variable in the environment
that will be passed to the command to be run.
Any existing environment variable with the same name will be replaced.
.It Fl h
Prints a usage message and exits.
.El
.Pp
The
.Ar prog
argument is the command to run, followed by any arguments to pass to the
command.
It can be a full or partial path, while a lone name will be looked up in the user's
command search path.
.Pp
If no architectures are specified on the command line, the
.Nm arch
command takes the basename of the
.Ar prog
argument and searches for the first property list file with that basename and
the
.Pa \&.plist
suffix, in the
.Pa archSettings
sub-directory in each of the standard domains, in the following order:
.Bl -tag -width ".Pa /Network/Library/archSettings" -offset indent
.It ~/Library/archSettings
User settings
.It /Library/archSettings
Local settings
.It /Network/Library/archSettings
Network settings
.It /System/Library/archSettings
System settings
.El
.Pp
This property list contains the architecture order preferences, as well
as the full path to the real executable.
For examples of the property list format, look at the files in
.Pa /System/Library/archSettings .
.Ss Example
On an intel processor:
.Bd -literal -offset indent
% perl -MConfig -e 'printf "%s\\n", $Config{byteorder}'
1234
.Ed
.Pp
shows the intel little endian byte order.
.Ss Making links to the arch command
When a link is made to
.Nm arch
command with a different name, that name is used to find
the corresponding property list file.
Thus, other commands can be wrapped so that they have custom architecture
selection order.
.Pp
Because of some internal logic in the code, hard links to the
.Nm arch
command may not work quite right.
It is best to avoid using hard links, and only use symbolic links to the
.Nm arch
command.
.Ss Environment
The environment variable
.Ev ARCHPREFERENCE
can be used to provide architecture order preferences.
It is checked before looking for the corresponding property list file.
.Pp
The value of the environment variable
.Ev ARCHPREFERENCE
is composed of one or more specifiers, separated by semicolons.
A specifier is made up of one, two or three fields, separated by colons.
Architectures specified in order, are separated by commas and make up the last
(mandatory) field.
The first field, if specified, is a name of a program, which selects this
specifier if that name matches the program name in question.
If the name field is empty or there is no name field, the specifier matches
any program name.
Thus, ordering of specifiers is important, and the one with no name should
be last.
.Pp
When the
.Nm arch
command is called directly, the
.Ar prog
name provides the path information to the executable (possibly via the command
search path).
When a name is specified in a
.Ev ARCHPREFERENCE
specifier, the path information can alternately be specified as a second
field following the name.
When the
.Nm arch
command is called indirectly via a link, this path information must be
specified.
If not specified as a second field in a specifier, the executable path will
be looked up in the corresponding property list file.
.Ss Example ARCHPREFERENCE Values
.Bl -tag -width "    "
.It i386,x86_64,x86_64h,arm64,arm64e
A specifier that matches any name.
.It foo:i386,x86_64,x86_64h,arm64,arm64e
A specifier that matches the program named
.Nm foo
(the full executable path is in the
.Pa foo.plist
file).
.It foo:/op/bin/boo:i386,x86_64,x86_64h,arm64,arm64e
A specifier with all fields specified.
.It baz:i386;x86_64;x86_64h,arm64,arm64e
A specifier for
.Nm baz
and a second specifier that would match any other name.
.El
.Sh BUGS
Running the
.Nm arch
command on an interpreter script may not work if the interpreter is a link
to the arch command, especially if a 64-bit architecture is specified (since the
.Nm arch
command is 2-way universal, 32-bit only).
.Sh SEE ALSO
.Xr machine 1
Commit	Line	Data
b51d5b5f A	1	.\" Copyright (c) 1994 SigmaSoft, Th. Lockert
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by SigmaSoft, Th. Lockert.
	15	.\" 4. The name of the author may not be used to endorse or promote products
	16	.\" derived from this software without specific prior written permission
	17	.\"
	18	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
	19	.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
	20	.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
	21	.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
	22	.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
	23	.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	24	.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	25	.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	26	.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
	27	.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	28	.\"
	29	.\" $OpenBSD: arch.1,v 1.2 1996/06/29 20:29:34 tholo Exp $
	30	.\"
	31	.\" Modifications made 8/20/97 (c) Apple Computer, Inc.
34d340d7	32	.\" Modifications made 11/12/06 (c) Apple Computer, Inc.
b51d5b5f	33
8459d725	34	.Dd July 8, 2010
b51d5b5f	35	.Dt ARCH 1
34d340d7	36	.Os "Mac OS X"
b51d5b5f A	37	.Sh NAME
b51d5b5f A	38	.Nm arch
34d340d7	39	.Nd print architecture type or run selected architecture of a universal binary
b51d5b5f A	40	.Sh SYNOPSIS
b51d5b5f A	41	.Nm arch
34d340d7	42	.Nm arch
8459d725 A	43	.Op Fl 32
8459d725 A	44	.Op Fl 64
34d340d7 A	45	.Oo
	46	.Oo Fl Ns Ar arch_name \| Fl arch Ar arch_name Oc Ns ...
	47	.Oc
8459d725 A	48	.Op Fl c
	49	.Oo Fl d Ar envname Oc Ns ...
	50	.Oo Fl e Ar envname=value Oc Ns ...
	51	.Op Fl h
34d340d7 A	52	.Ar prog
34d340d7 A	53	.Op Ar args No ...
b51d5b5f A	54	.Sh DESCRIPTION
	55	The
	56	.Nm arch
34d340d7 A	57	command with no arguments, displays the machine's architecture type.
	58	.Pp
	59	The other use of the
	60	.Nm arch
d52496fd	61	command is to run a selected architecture of a universal binary.
34d340d7 A	62	A universal binary contains code that can run on different architectures.
	63	By default, the operating system will select the architecture that most closely
	64	matches the processor type.
ef8ad44b	65	A 64-bit architecture is preferred over a 32-bit architecture on a 64-bit
34d340d7 A	66	processor, while only 32-bit architectures can run on a 32-bit processor.
	67	.Pp
	68	When the most natural architecture is unavailable, the operating system will
	69	try to pick another architecture.
	70	On 64-bit processors, a 32-bit architecture is tried.
34d340d7 A	71	Otherwise, no architecture is run, and an error results.
	72	.Pp
	73	The
	74	.Nm arch
ef8ad44b	75	command can be used to alter the operating system's normal selection order.
34d340d7 A	76	The most common use is to select the 32-bit architecture on a 64-bit processor,
	77	even if a 64-bit architecture is available.
	78	.Pp
	79	The
34d340d7 A	80	.Ar arch_name
34d340d7 A	81	argument must be one of the currently supported architectures:
c0bbac3a	82	.Bl -tag -width x86_64h -offset indent
34d340d7 A	83	.It i386
34d340d7 A	84	32-bit intel
34d340d7 A	85	.It x86_64
34d340d7 A	86	64-bit intel
c0bbac3a A	87	.It x86_64h
c0bbac3a A	88	64-bit intel (haswell)
0813f9a6 A	89	.It arm64
	90	64-bit arm
	91	.It arm64e
	92	64-bit arm (Apple Silicon)
34d340d7 A	93	.El
34d340d7 A	94	.Pp
0813f9a6 A	95	If the binary does not contain code for
	96	.Ar arch_name ,
	97	the
	98	.Nm arch
	99	command may try to select a close match. If arm64 is specified and not found,
	100	arm64e will be tried next. If this happens, the order the architectures will
	101	be tried is not guaranteed.
	102	.Pp
34d340d7 A	103	Either prefix the architecture with a hyphen, or (for compatibility with
	104	other commands), use
	105	.Fl arch
	106	followed by the architecture.
	107	.Pp
	108	If more than one architecture is specified, the operating system will try each
	109	one in order, skipping an architecture that is not supported on the current
	110	processor, or is unavailable in the universal binary.
	111	.Pp
8459d725 A	112	The other options are:
	113	.Bl -tag -width ".Fl e Ar envname=value"
	114	.It Fl 32
	115	Add the native 32-bit architecture to the list of architectures.
	116	.It Fl 64
	117	Add the native 64-bit architecture to the list of architectures.
	118	.It Fl c
	119	Clears the environment that will be passed to the command to be run.
	120	.It Fl d Ar envname
	121	Deletes the named environment variable from the environment that will be passed
	122	to the command to be run.
	123	.It Fl e Ar envname=value
	124	Assigns the given value to the named environment variable in the environment
	125	that will be passed to the command to be run.
	126	Any existing environment variable with the same name will be replaced.
	127	.It Fl h
	128	Prints a usage message and exits.
	129	.El
	130	.Pp
34d340d7 A	131	The
	132	.Ar prog
	133	argument is the command to run, followed by any arguments to pass to the
	134	command.
ef8ad44b	135	It can be a full or partial path, while a lone name will be looked up in the user's
34d340d7 A	136	command search path.
	137	.Pp
	138	If no architectures are specified on the command line, the
	139	.Nm arch
	140	command takes the basename of the
	141	.Ar prog
	142	argument and searches for the first property list file with that basename and
	143	the
	144	.Pa \&.plist
	145	suffix, in the
	146	.Pa archSettings
	147	sub-directory in each of the standard domains, in the following order:
	148	.Bl -tag -width ".Pa /Network/Library/archSettings" -offset indent
	149	.It ~/Library/archSettings
	150	User settings
	151	.It /Library/archSettings
	152	Local settings
	153	.It /Network/Library/archSettings
	154	Network settings
	155	.It /System/Library/archSettings
	156	System settings
	157	.El
	158	.Pp
	159	This property list contains the architecture order preferences, as well
	160	as the full path to the real executable.
	161	For examples of the property list format, look at the files in
	162	.Pa /System/Library/archSettings .
	163	.Ss Example
	164	On an intel processor:
	165	.Bd -literal -offset indent
	166	% perl -MConfig -e 'printf "%s\\n", $Config{byteorder}'
	167	1234
	168	.Ed
	169	.Pp
8459d725	170	shows the intel little endian byte order.
34d340d7 A	171	.Ss Making links to the arch command
	172	When a link is made to
	173	.Nm arch
	174	command with a different name, that name is used to find
	175	the corresponding property list file.
	176	Thus, other commands can be wrapped so that they have custom architecture
	177	selection order.
	178	.Pp
	179	Because of some internal logic in the code, hard links to the
	180	.Nm arch
	181	command may not work quite right.
	182	It is best to avoid using hard links, and only use symbolic links to the
	183	.Nm arch
	184	command.
	185	.Ss Environment
	186	The environment variable
	187	.Ev ARCHPREFERENCE
	188	can be used to provide architecture order preferences.
	189	It is checked before looking for the corresponding property list file.
	190	.Pp
	191	The value of the environment variable
	192	.Ev ARCHPREFERENCE
	193	is composed of one or more specifiers, separated by semicolons.
	194	A specifier is made up of one, two or three fields, separated by colons.
	195	Architectures specified in order, are separated by commas and make up the last
	196	(mandatory) field.
	197	The first field, if specified, is a name of a program, which selects this
	198	specifier if that name matches the program name in question.
	199	If the name field is empty or there is no name field, the specifier matches
	200	any program name.
	201	Thus, ordering of specifiers is important, and the one with no name should
	202	be last.
	203	.Pp
	204	When the
	205	.Nm arch
	206	command is called directly, the
	207	.Ar prog
	208	name provides the path information to the executable (possibly via the command
	209	search path).
	210	When a name is specified in a
	211	.Ev ARCHPREFERENCE
	212	specifier, the path information can alternately be specified as a second
	213	field following the name.
	214	When the
	215	.Nm arch
	216	command is called indirectly via a link, this path information must be
	217	specified.
	218	If not specified as a second field in a specifier, the executable path will
	219	be looked up in the corresponding property list file.
	220	.Ss Example ARCHPREFERENCE Values
	221	.Bl -tag -width " "
0813f9a6	222	.It i386,x86_64,x86_64h,arm64,arm64e
34d340d7	223	A specifier that matches any name.
0813f9a6	224	.It foo:i386,x86_64,x86_64h,arm64,arm64e
34d340d7 A	225	A specifier that matches the program named
	226	.Nm foo
	227	(the full executable path is in the
	228	.Pa foo.plist
	229	file).
0813f9a6	230	.It foo:/op/bin/boo:i386,x86_64,x86_64h,arm64,arm64e
34d340d7	231	A specifier with all fields specified.
0813f9a6	232	.It baz:i386;x86_64;x86_64h,arm64,arm64e
34d340d7 A	233	A specifier for
	234	.Nm baz
	235	and a second specifier that would match any other name.
	236	.El
	237	.Sh BUGS
	238	Running the
	239	.Nm arch
	240	command on an interpreter script may not work if the interpreter is a link
	241	to the arch command, especially if a 64-bit architecture is specified (since the
	242	.Nm arch
	243	command is 2-way universal, 32-bit only).
b51d5b5f A	244	.Sh SEE ALSO
b51d5b5f A	245	.Xr machine 1