git.saurik.com Git - apple/xnu.git/blob - bsd/man/man3/posix_spawnattr_setbinpref

1 .\"

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.