[apple/libutil.git] / reexec_to_match_kernel.3

.Dd Apr 14, 2008
.Dt REEXEC_TO_MATCH_KERNEL 3
.Os "Mac OS X"
.Sh NAME
.Nm reexec_to_match_kernel
.Nd Re-exec the current binary to match the ABI of the running kernel
.Sh LIBRARY
.Lb libutil
.Sh SYNOPSIS
.In libutil.h
.Ft int
.Fo reexec_to_match_kernel
.Fa "void"
.Fc
.Ft int
.Fo reexec_to_match_lp64ness
.Fa "bool isLP64"
.Fc
.Sh DESCRIPTION
The
.Fn reexec_to_match_kernel
function re-executes the current binary to match the ABI of the running kernel.
That is, if the current kernel is a 64-bit Intel kernel, it will attempt to
execute the 64-bit x86_64 userspace slice of the universal binary. The API
intentionally does not take arguments because its use should be transparent
to the program and to the user.
.Pp
The
.Fn reexec_to_match_lp64ness
is coarser-grained, and only attempts to match the word width that is requested.
For example, if the current system defaults to executing the 64-bit x86_64
userspace slice, but the program should instead run in 32-bit i386 mode,
this routine can be used.
.Pp
Both
.Fn reexec_to_match_kernel
and
.Fn reexec_to_match_lp64ness
can each be used exactly once in a program's lifetime. In certain circumstances,
it may even be desirable to use one, and then the other.
.Sh RETURN VALUES
The
.Fn reexec_to_match_kernel
and
.Fn reexec_to_match_lp64ness
functions return 0 if re-execution was not required. It returns -1 and
sets errno if there was an error performing the re-execution, for example
if the binary is not universal, or does not contain a slice to match the running
kernel's ABI. If the function succeeds, control never returns to the caller
and the program starts from main() again.
Commit	Line	Data
1bd2040a A	1	.Dd Apr 14, 2008
	2	.Dt REEXEC_TO_MATCH_KERNEL 3
	3	.Os "Mac OS X"
	4	.Sh NAME
	5	.Nm reexec_to_match_kernel
	6	.Nd Re-exec the current binary to match the ABI of the running kernel
	7	.Sh LIBRARY
	8	.Lb libutil
	9	.Sh SYNOPSIS
	10	.In libutil.h
	11	.Ft int
	12	.Fo reexec_to_match_kernel
	13	.Fa "void"
	14	.Fc
e682b5d1 A	15	.Ft int
	16	.Fo reexec_to_match_lp64ness
	17	.Fa "bool isLP64"
	18	.Fc
1bd2040a A	19	.Sh DESCRIPTION
	20	The
	21	.Fn reexec_to_match_kernel
	22	function re-executes the current binary to match the ABI of the running kernel.
	23	That is, if the current kernel is a 64-bit Intel kernel, it will attempt to
	24	execute the 64-bit x86_64 userspace slice of the universal binary. The API
	25	intentionally does not take arguments because its use should be transparent
	26	to the program and to the user.
e682b5d1 A	27	.Pp
	28	The
	29	.Fn reexec_to_match_lp64ness
	30	is coarser-grained, and only attempts to match the word width that is requested.
	31	For example, if the current system defaults to executing the 64-bit x86_64
	32	userspace slice, but the program should instead run in 32-bit i386 mode,
	33	this routine can be used.
	34	.Pp
	35	Both
	36	.Fn reexec_to_match_kernel
	37	and
	38	.Fn reexec_to_match_lp64ness
	39	can each be used exactly once in a program's lifetime. In certain circumstances,
	40	it may even be desirable to use one, and then the other.
1bd2040a A	41	.Sh RETURN VALUES
	42	The
	43	.Fn reexec_to_match_kernel
e682b5d1 A	44	and
	45	.Fn reexec_to_match_lp64ness
	46	functions return 0 if re-execution was not required. It returns -1 and
1bd2040a A	47	sets errno if there was an error performing the re-execution, for example
	48	if the binary is not universal, or does not contain a slice to match the running
	49	kernel's ABI. If the function succeeds, control never returns to the caller
	50	and the program starts from main() again.