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