system_cmds/arch.tproj/arch.1

   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.
  32 .\" Modifications made 11/12/06 (c) Apple Computer, Inc.
  33
  34 .Dd July 8, 2010
  35 .Dt ARCH 1
  36 .Os "Mac OS X"
  37 .Sh NAME
  38 .Nm arch
  39 .Nd print architecture type or run selected architecture of a universal binary
  40 .Sh SYNOPSIS
  41 .Nm arch
  42 .Nm arch
  43 .Op Fl 32
  44 .Op Fl 64
  45 .Oo
  46 .Oo Fl Ns Ar arch_name | Fl arch Ar arch_name Oc Ns ...
  47 .Oc
  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
  52 .Ar prog
  53 .Op Ar args No ...
  54 .Sh DESCRIPTION
  55 The
  56 .Nm arch
  57 command with no arguments, displays the machine's architecture type.
  58 .Pp
  59 The other use of the
  60 .Nm arch
  61 command is to run a selected architecture of a universal binary.
  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.
  65 A 64-bit architecture is preferred over a 32-bit architecture on a 64-bit
  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.
  71 Otherwise, no architecture is run, and an error results.
  72 .Pp
  73 The
  74 .Nm arch
  75 command can be used to alter the operating system's normal selection order.
  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
  80 .Ar arch_name
  81 argument must be one of the currently supported architectures:
  82 .Bl -tag -width x86_64h -offset indent
  83 .It i386
  84 32-bit intel
  85 .It x86_64
  86 64-bit intel
  87 .It x86_64h
  88 64-bit intel (haswell)
  89 .It arm64
  90 64-bit arm
  91 .It arm64e
  92 64-bit arm (Apple Silicon)
  93 .El
  94 .Pp
  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
 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
 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
 131 The
 132 .Ar prog
 133 argument is the command to run, followed by any arguments to pass to the
 134 command.
 135 It can be a full or partial path, while a lone name will be looked up in the user's
 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
 170 shows the intel little endian byte order.
 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 "    "
 222 .It i386,x86_64,x86_64h,arm64,arm64e
 223 A specifier that matches any name.
 224 .It foo:i386,x86_64,x86_64h,arm64,arm64e
 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).
 230 .It foo:/op/bin/boo:i386,x86_64,x86_64h,arm64,arm64e
 231 A specifier with all fields specified.
 232 .It baz:i386;x86_64;x86_64h,arm64,arm64e
 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).
 244 .Sh SEE ALSO
 245 .Xr machine 1