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