bsd/man/man3/posix_spawnattr_setbinpref_np.3

   1 .\"
   2 .\" Copyright (c) 2000-2007 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_setbinpref_np.3
  29 .
  30 .Dd May 8, 2020
  31 .Dt POSIX_SPAWNATTR_SETBINPREF_NP 3
  32 .Os "Mac OS X"
  33 .Sh NAME
  34 .Nm posix_spawnattr_setbinpref_np
  35 .Nm posix_spawnattr_getbinpref_np
  36 .Nd set or get the
  37 .Em spawn-binpref
  38 attribute on a
  39 .Em posix_spawnattr_t
  40 .Sh SYNOPSIS
  41 .Fd #include <spawn.h>
  42 .Ft int
  43 .Fo posix_spawnattr_setbinpref_np
  44 .Fa "posix_spawnattr_t *restrict attr"
  45 .Fa "size_t count"
  46 .Fa "cpu_type_t *pref"
  47 .Fa "size_t *restrict ocount"
  48 .Fc
  49 .Ft int
  50 .Fo posix_spawnattr_getbinpref_np
  51 .Fa "const posix_spawnattr_t *restrict attr"
  52 .Fa "size_t count"
  53 .Fa "cpu_type_t *pref"
  54 .Fa "size_t * restrict ocount"
  55 .Fc
  56 .Sh IMPORTANT
  57 These functions represent an Apple extension to
  58 .Xr posix_spawn 2
  59 and
  60 .Xr posix_spawnp 2 ,
  61 and as such should not be used by programs intending their code to be
  62 portable to other platforms.
  63 .Sh DESCRIPTION
  64 The
  65 .Fn posix_spawnattr_setbinpref_np
  66 function sets the universal binary preferences for the spawn attribute
  67 value referenced by
  68 .Fa attr
  69 from the memory containing the
  70 .Em cpu_type_t
  71 referenced by
  72 .Fa pref
  73 with a size of
  74 .Fa count
  75 elements; the actual number of elements that are set in the attribute
  76 is returned in
  77 .Fa ocount .
  78 .Pp
  79 When
  80 .Xr spawn 2
  81 or
  82 .Xr spawnp 2
  83 is subsequently invoked on a Universal binary with the
  84 .Em posix_spawnattr_t ,
  85 the elements which were set will be used, in the order they were set,
  86 to select the first element in the list which matches any
  87 .Em cpu_type_t
  88 of those available in the Universal binary, using the best slice matching
  89 that
  90 .Em cpu_type_t .
  91 If there is no match, then
  92 the attempt to create the child process will fail with the error
  93 EBADARCH.
  94 If the
  95 .Em cpu_type_t
  96 .Em CPU_TYPE_ANY
  97 is the last element in the list, then rather than returning
  98 EBADARCH
  99 on no match, the system will instead fall back to the standard Universal
 100 binary grading preference order.
 101 If called multiple times on the same
 102 .Em attr ,
 103 the previous preferences will be overwritten.
 104 .Pp
 105 The
 106 .Fn posix_spawnattr_getbinpref_np
 107 function gets the universal binary preferences for the spawn attribute
 108 value referenced by
 109 .Fa attr
 110 (set by a prior call to
 111 .Fn posix_spawnattr_setbinpref_np
 112 or
 113 .Fn posix_spawnattr_setarchpref_np )
 114 into the memory containing the
 115 .Em cpu_type_t
 116 referenced by
 117 .Fa pref
 118 with a prereserved size of
 119 .Fa count
 120 elements; the actual number of elements that are copied from the attribute
 121 is returned in
 122 .Fa ocount .
 123 .Pp
 124 .Sh RETURN VALUES
 125 On success, these functions return 0; on failure they return an error
 126 number from
 127 .In errno.h
 128 and modify the value of
 129 .Fa ocount .
 130 Additionally, if successful,
 131 .Fn posix_spawnattr_getbinpref_np
 132 will modify the contents of the
 133 .Fa pref
 134 array with the current attribute values.
 135 .Sh ERRORS
 136 These functions may fail if:
 137 .Bl -tag -width Er
 138 .\" ==========
 139 .It Bq Er EINVAL
 140 The value specified by
 141 .Fa attr
 142 is invalid.
 143 .\" ==========
 144 .It Bq Er EINVAL
 145 The value of
 146 .Fa attr
 147 is invalid.
 148 .El
 149 .Sh SEE ALSO
 150 .Xr posix_spawn 2 ,
 151 .Xr posix_spawnp 2 ,
 152 .Xr posix_spawnattr_init 3 ,
 153 .Xr posix_spawnattr_destroy 3 ,
 154 .Xr posix_spawnattr_setarchpref_np 3
 155 .Xr posix_spawnattr_setflags 3
 156 .Sh STANDARDS
 157 Nonstandard
 158 .Sh HISTORY
 159 The
 160 .Fn posix_spawnattr_setbinpref_np
 161 and
 162 .Fn posix_spawnattr_getbinpref_np
 163 function calls appeared in Mac OS X.