bsd/man/man3/posix_spawnattr_setarchpref_np.3

   1 .\"
   2 .\" Copyright (c) 2020 Apple Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the 'License'). You may not use this file except in
   9 .\" compliance with the License. The rights granted to you under the License
  10 .\" may not be used to create, or enable the creation or redistribution of,
  11 .\" unlawful or unlicensed copies of an Apple operating system, or to
  12 .\" circumvent, violate, or enable the circumvention or violation of, any
  13 .\" terms of an Apple operating system software license agreement.
  14 .\"
  15 .\" Please obtain a copy of the License at
  16 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
  17 .\"
  18 .\" The Original Code and all software distributed under the License are
  19 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23 .\" Please see the License for the specific language governing rights and
  24 .\" limitations under the License.
  25 .\"
  26 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27 .\"
  28 .\"     @(#)posix_spawnattr_setarchpref_np.3
  29 .
  30 .Dd May 8, 2020
  31 .Dt POSIX_SPAWNATTR_SETARCHPREF_NP 3
  32 .Os "Mac OS X"
  33 .Sh NAME
  34 .Nm posix_spawnattr_setarchpref_np
  35 .Nm posix_spawnattr_getarchpref_np
  36 .Nd set or get the
  37 .Em cpu/subcpu preference
  38 attribute on a
  39 .Em posix_spawnattr_t
  40 .Sh SYNOPSIS
  41 .Fd #include <spawn.h>
  42 .Ft int
  43 .Fo posix_spawnattr_setarchpref_np
  44 .Fa "posix_spawnattr_t *restrict attr"
  45 .Fa "size_t count"
  46 .Fa "cpu_type_t *pref"
  47 .Fa "cpu_subtype_t *subpref"
  48 .Fa "size_t *restrict ocount"
  49 .Fc
  50 .Ft int
  51 .Fo posix_spawnattr_getarchpref_np
  52 .Fa "const posix_spawnattr_t *restrict attr"
  53 .Fa "size_t count"
  54 .Fa "cpu_type_t *pref"
  55 .Fa "cpu_subtype_t *subpref"
  56 .Fa "size_t * restrict ocount"
  57 .Fc
  58 .Sh IMPORTANT
  59 These functions represent an Apple extension to
  60 .Xr posix_spawn 2
  61 and
  62 .Xr posix_spawnp 2 ,
  63 and as such should not be used by programs intending their code to be
  64 portable to other platforms.
  65 .Sh DESCRIPTION
  66 The
  67 .Fn posix_spawnattr_setarchpref_np
  68 function sets the precise universal binary preferences for the spawn attribute
  69 value referenced by
  70 .Fa attr
  71 from the memory containing the
  72 .Em cpu_type_t
  73 referenced by
  74 .Fa pref
  75 and the
  76 .Em cpu_subtype_t
  77 referenced by
  78 .Fa subpref
  79 with a size of
  80 .Fa count
  81 elements; the actual number of elements that are set in the attribute
  82 is returned in
  83 .Fa ocount .
  84 .Pp
  85 When
  86 .Xr spawn 2
  87 or
  88 .Xr spawnp 2
  89 is subsequently invoked on a Universal binary with the
  90 .Em posix_spawnattr_t ,
  91 the elements which were set will be used, in the order they were set,
  92 to select the first element in the list which matches any
  93 .Em cpu_type_t
  94 and
  95 .Em cpu_subtype_t
  96 of those available in the Universal binary.  If there is no match, then
  97 the attempt to create the child process will fail with the error
  98 EBADARCH.
  99 If the
 100 .Em cpu_type_t
 101 .Em CPU_TYPE_ANY
 102 and
 103 .Em cpu_subtype_t
 104 .Em CPU_SUBTYPE_ANY
 105 are the last pair in the list, then rather than returning
 106 EBADARCH
 107 on no match, the system will instead fall back to the standard Universal
 108 binary grading preference order. Using
 109 .Em CPU_SUBTYPE_ANY
 110 as a
 111 .Em cpu_subtype_t
 112 for any
 113 .Em cpu_type_t
 114 value will select the best slice for that specific
 115 .Em cpu_type_t ,
 116 similar to using
 117 .Fn posix_spawnattr_setbinpref_np .
 118 If called multiple times on the same
 119 .Em attr ,
 120 the previous preferences will be overwritten.
 121 .Pp
 122 The
 123 .Fn posix_spawnattr_getarchpref_np
 124 function gets the precise universal binary preferences for the spawn attribute
 125 value referenced by
 126 .Fa attr
 127 (set by a prior call to
 128 .Fn posix_spawnattr_setbinpref_np
 129 or
 130 .Fn posix_spawnattr_setarchpref_np )
 131 into the memory
 132 containing the
 133 .Em cpu_type_t
 134 referenced by
 135 .Fa pref
 136 and the
 137 .Em cpu_subtype_t
 138 referenced by
 139 .Fa subpref
 140 with a prereserved size of
 141 .Fa count
 142 elements; the actual number of elements that are copied from the attribute
 143 is returned in
 144 .Fa ocount .
 145 .Pp
 146 .Sh RETURN VALUES
 147 On success, these functions return 0; on failure they return an error
 148 number from
 149 .In errno.h
 150 and modify the value of
 151 .Fa ocount .
 152 Additionally, if successful,
 153 .Fn posix_spawnattr_getarchpref_np
 154 will modify the contents of the
 155 .Fa pref
 156 array with the current attribute values.
 157 .Sh ERRORS
 158 These functions may fail if:
 159 .Bl -tag -width Er
 160 .\" ==========
 161 .It Bq Er EINVAL
 162 The value specified by
 163 .Fa attr
 164 is invalid.
 165 .\" ==========
 166 .It Bq Er EINVAL
 167 The value of
 168 .Fa attr
 169 is invalid.
 170 .El
 171 .Sh SEE ALSO
 172 .Xr posix_spawn 2 ,
 173 .Xr posix_spawnp 2 ,
 174 .Xr posix_spawnattr_init 3 ,
 175 .Xr posix_spawnattr_destroy 3 ,
 176 .Xr posix_spawnattr_setbinpref_np 3 ,
 177 .Xr posix_spawnattr_setflags 3
 178 .Sh STANDARDS
 179 Nonstandard
 180 .Sh HISTORY
 181 The
 182 .Fn posix_spawnattr_setarchpref_np
 183 and
 184 .Fn posix_spawnattr_getarchpref_np
 185 function calls appeared in macOS 10.16