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

... / ...

Commit	Line	Data
	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.