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 August 22, 2007
  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.  If there is no match, then
  89 the attempt to create the child process will fail with the error
  90 EBADARCH.
  91 If the
  92 .Em cpu_type_t
  93 .Em CPU_TYPE_ANY
  94 is the last element in the list, then rather than returning
  95 EBADARCH
  96 on no match, the system will instead fall back to the standard Universal
  97 binary grading preference order.
  98 .Pp
  99 The
 100 .Fn posix_spawnattr_getbinpref_np
 101 function gets the universal binary preferences for the spawn attribute
 102 value referenced by
 103 .Fa attr
 104 into the memory containing the
 105 .Em cpu_type_t
 106 referenced by
 107 .Fa pref
 108 with a prereserved size of
 109 .Fa count
 110 elements; the actual number of elements that are copied from the attribute
 111 is returned in
 112 .Fa ocount .
 113 .Pp
 114 .Sh RETURN VALUES
 115 On success, these functions return 0; on failure they return an error
 116 number from
 117 .In errno.h
 118 and modify the value of
 119 .Fa ocount .
 120 Additionally, if successful,
 121 .Fn posix_spawnattr_getbinpref_np
 122 will modify the contents of the
 123 .Fa pref
 124 array with the current attribute values.
 125 .Sh ERRORS
 126 These functions may fail if:
 127 .Bl -tag -width Er
 128 .\" ==========
 129 .It Bq Er EINVAL
 130 The value specified by
 131 .Fa attr
 132 is invalid.
 133 .\" ==========
 134 .It Bq Er EINVAL
 135 The value of
 136 .Fa attr
 137 is invalid.
 138 .El
 139 .Sh SEE ALSO
 140 .Xr posix_spawn 2 ,
 141 .Xr posix_spawnp 2 ,
 142 .Xr posix_spawnattr_init 3 ,
 143 .Xr posix_spawnattr_destroy 3 ,
 144 .Xr posix_spawnattr_setflags 3
 145 .Sh STANDARDS
 146 Nonstandard
 147 .Sh HISTORY
 148 The
 149 .Fn posix_spawnattr_setbinpref_np
 150 and
 151 .Fn posix_spawnattr_getbinpref_np
 152 function calls appeared in Mac OS X.