[apple/xnu.git] / bsd / man / man3 / posix_spawnattr_setbinpref_np.3

.\"
.\" Copyright (c) 2000-2007 Apple Inc. All rights reserved.
.\"
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
.\" 
.\" This file contains Original Code and/or Modifications of Original Code
.\" as defined in and that are subject to the Apple Public Source License
.\" Version 2.0 (the 'License'). You may not use this file except in
.\" compliance with the License. The rights granted to you under the License
.\" may not be used to create, or enable the creation or redistribution of,
.\" unlawful or unlicensed copies of an Apple operating system, or to
.\" circumvent, violate, or enable the circumvention or violation of, any
.\" terms of an Apple operating system software license agreement.
.\" 
.\" Please obtain a copy of the License at
.\" http://www.opensource.apple.com/apsl/ and read it before using this file.
.\" 
.\" The Original Code and all software distributed under the License are
.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
.\" Please see the License for the specific language governing rights and
.\" limitations under the License.
.\" 
.\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
.\"
.\"     @(#)posix_spawnattr_setbinpref_np.3
.
.Dd August 22, 2007
.Dt POSIX_SPAWNATTR_SETBINPREF_NP 3
.Os "Mac OS X"
.Sh NAME
.Nm posix_spawnattr_setbinpref_np
.Nm posix_spawnattr_getbinpref_np
.Nd set or get the
.Em spawn-binpref
attribute on a
.Em posix_spawnattr_t
.Sh SYNOPSIS
.Fd #include <spawn.h>
.Ft int
.Fo posix_spawnattr_setbinpref_np
.Fa "posix_spawnattr_t *restrict attr"
.Fa "size_t count"
.Fa "cpu_type_t *pref"
.Fa "size_t *restrict ocount"
.Fc
.Ft int
.Fo posix_spawnattr_getbinpref_np
.Fa "const posix_spawnattr_t *restrict attr"
.Fa "size_t count"
.Fa "cpu_type_t *pref"
.Fa "size_t * restrict ocount"
.Fc
.Sh IMPORTANT
These functions represent an Apple extension to
.Xr posix_spawn 2
and
.Xr posix_spawnp 2 ,
and as such should not be used by programs intending their code to be
portable to other platforms.
.Sh DESCRIPTION
The
.Fn posix_spawnattr_setbinpref_np
function sets the universal binary preferences for the spawn attribute
value referenced by
.Fa attr
from the memory containing the
.Em cpu_type_t
referenced by 
.Fa pref
with a size of
.Fa count
elements; the actual number of elements that are set in the attribute
is returned in
.Fa ocount .
.Pp
When
.Xr spawn 2
or
.Xr spawnp 2
is subsequently invoked on a Universal binary with the
.Em posix_spawnattr_t ,
the elements which were set will be used, in the order they were set,
to select the first element in the list which matches any
.Em cpu_type_t
of those available in the Universal binary.  If there is no match, then
the attempt to create the child process will fail with the error
EBADARCH.
If the
.Em cpu_type_t
.Em CPU_TYPE_ANY
is the last element in the list, then rather than returning
EBADARCH
on no match, the system will instead fall back to the standard Universal
binary grading preference order.
.Pp
The
.Fn posix_spawnattr_getbinpref_np
function gets the universal binary preferences for the spawn attribute
value referenced by
.Fa attr
into the memory containing the
.Em cpu_type_t
referenced by 
.Fa pref
with a prereserved size of
.Fa count
elements; the actual number of elements that are copied from the attribute
is returned in
.Fa ocount .
.Pp
.Sh RETURN VALUES
On success, these functions return 0; on failure they return an error
number from
.In errno.h 
and modify the value of
.Fa ocount .
Additionally, if successful,
.Fn posix_spawnattr_getbinpref_np
will modify the contents of the
.Fa pref
array with the current attribute values.
.Sh ERRORS
These functions may fail if:
.Bl -tag -width Er
.\" ==========
.It Bq Er EINVAL
The value specified by
.Fa attr
is invalid.
.\" ==========
.It Bq Er EINVAL
The value of
.Fa attr
is invalid.
.El
.Sh SEE ALSO
.Xr posix_spawn 2 ,
.Xr posix_spawnp 2 ,
.Xr posix_spawnattr_init 3 ,
.Xr posix_spawnattr_destroy 3 ,
.Xr posix_spawnattr_setflags 3
.Sh STANDARDS
Nonstandard
.Sh HISTORY
The
.Fn posix_spawnattr_setbinpref_np
and
.Fn posix_spawnattr_getbinpref_np
function calls appeared in Mac OS X.
Commit	Line	Data
2d21ac55 A	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.