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 .El
  90 .Pp
  91 Either prefix the architecture with a hyphen, or (for compatibility with
  92 other commands), use
  93 .Fl arch
  94 followed by the architecture.
  95 .Pp
  96 If more than one architecture is specified, the operating system will try each
  97 one in order, skipping an architecture that is not supported on the current
  98 processor, or is unavailable in the universal binary.
  99 .Pp
 100 The other options are:
 101 .Bl -tag -width ".Fl e Ar envname=value"
 102 .It Fl 32
 103 Add the native 32-bit architecture to the list of architectures.
 104 .It Fl 64
 105 Add the native 64-bit architecture to the list of architectures.
 106 .It Fl c
 107 Clears the environment that will be passed to the command to be run.
 108 .It Fl d Ar envname
 109 Deletes the named environment variable from the environment that will be passed
 110 to the command to be run.
 111 .It Fl e Ar envname=value
 112 Assigns the given value to the named environment variable in the environment
 113 that will be passed to the command to be run.
 114 Any existing environment variable with the same name will be replaced.
 115 .It Fl h
 116 Prints a usage message and exits.
 117 .El
 118 .Pp
 119 The
 120 .Ar prog
 121 argument is the command to run, followed by any arguments to pass to the
 122 command.
 123 It can be a full or partial path, while a lone name will be looked up in the user's
 124 command search path.
 125 .Pp
 126 If no architectures are specified on the command line, the
 127 .Nm arch
 128 command takes the basename of the
 129 .Ar prog
 130 argument and searches for the first property list file with that basename and
 131 the
 132 .Pa \&.plist
 133 suffix, in the
 134 .Pa archSettings
 135 sub-directory in each of the standard domains, in the following order:
 136 .Bl -tag -width ".Pa /Network/Library/archSettings" -offset indent
 137 .It ~/Library/archSettings
 138 User settings
 139 .It /Library/archSettings
 140 Local settings
 141 .It /Network/Library/archSettings
 142 Network settings
 143 .It /System/Library/archSettings
 144 System settings
 145 .El
 146 .Pp
 147 This property list contains the architecture order preferences, as well
 148 as the full path to the real executable.
 149 For examples of the property list format, look at the files in
 150 .Pa /System/Library/archSettings .
 151 .Ss Example
 152 On an intel processor:
 153 .Bd -literal -offset indent
 154 % perl -MConfig -e 'printf "%s\\n", $Config{byteorder}'
 155 1234
 156 .Ed
 157 .Pp
 158 shows the intel little endian byte order.
 159 .Ss Making links to the arch command
 160 When a link is made to
 161 .Nm arch
 162 command with a different name, that name is used to find
 163 the corresponding property list file.
 164 Thus, other commands can be wrapped so that they have custom architecture
 165 selection order.
 166 .Pp
 167 Because of some internal logic in the code, hard links to the
 168 .Nm arch
 169 command may not work quite right.
 170 It is best to avoid using hard links, and only use symbolic links to the
 171 .Nm arch
 172 command.
 173 .Ss Environment
 174 The environment variable
 175 .Ev ARCHPREFERENCE
 176 can be used to provide architecture order preferences.
 177 It is checked before looking for the corresponding property list file.
 178 .Pp
 179 The value of the environment variable
 180 .Ev ARCHPREFERENCE
 181 is composed of one or more specifiers, separated by semicolons.
 182 A specifier is made up of one, two or three fields, separated by colons.
 183 Architectures specified in order, are separated by commas and make up the last
 184 (mandatory) field.
 185 The first field, if specified, is a name of a program, which selects this
 186 specifier if that name matches the program name in question.
 187 If the name field is empty or there is no name field, the specifier matches
 188 any program name.
 189 Thus, ordering of specifiers is important, and the one with no name should
 190 be last.
 191 .Pp
 192 When the
 193 .Nm arch
 194 command is called directly, the
 195 .Ar prog
 196 name provides the path information to the executable (possibly via the command
 197 search path).
 198 When a name is specified in a
 199 .Ev ARCHPREFERENCE
 200 specifier, the path information can alternately be specified as a second
 201 field following the name.
 202 When the
 203 .Nm arch
 204 command is called indirectly via a link, this path information must be
 205 specified.
 206 If not specified as a second field in a specifier, the executable path will
 207 be looked up in the corresponding property list file.
 208 .Ss Example ARCHPREFERENCE Values
 209 .Bl -tag -width "    "
 210 .It i386,x86_64,x86_64h
 211 A specifier that matches any name.
 212 .It foo:i386,x86_64,x86_64h
 213 A specifier that matches the program named
 214 .Nm foo
 215 (the full executable path is in the
 216 .Pa foo.plist
 217 file).
 218 .It foo:/op/bin/boo:i386,x86_64,x86_64h
 219 A specifier with all fields specified.
 220 .It baz:i386;x86_64;x86_64h
 221 A specifier for
 222 .Nm baz
 223 and a second specifier that would match any other name.
 224 .El
 225 .Sh BUGS
 226 Running the
 227 .Nm arch
 228 command on an interpreter script may not work if the interpreter is a link
 229 to the arch command, especially if a 64-bit architecture is specified (since the
 230 .Nm arch
 231 command is 2-way universal, 32-bit only).
 232 .Sh SEE ALSO
 233 .Xr machine 1