xnu-1228.7.58.tar.gz

[apple/xnu.git] / bsd / man / man3 / posix_spawnattr_setflags.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_setflags.3
.
.Dd August 22, 2007
.Dt POSIX_SPAWNATTR_SETFLAGS 3
.Os "Mac OS X"
.Sh NAME
.Nm posix_spawnattr_setflags
.Nm posix_spawnattr_getflags
.Nd get or set flags on a
.Em posix_spawnattr_t
.Sh SYNOPSIS
.Fd #include <spawn.h>
.Ft int
.Fo posix_spawnattr_setflags
.Fa "posix_spawnattr_t *attr"
.Fa "short flags"
.Fc
.Ft int
.Fo posix_spawnattr_getflags
.Fa "const posix_spawnattr_t *restrict attr"
.Fa "short *restrict flags"
.Fc
.Sh DESCRIPTION
The
.Fn posix_spawnattr_setflags
function sets the
.Fa flags
on the attributes object referenced by
.Fa attr .
.Pp
The
.Fn posix_spawnattr_getflags
function retrieves the
.Fa flags
on the attributes object referenced by
.Fa attr .
.Pp
The argument
.Fa flags
is either 0 or a logical OR of one or more of the following flags:
.Bl -tag -width POSIX_SPAWN_START_SUSPENDED
.It Dv POSIX_SPAWN_RESETIDS
If the set group bit is set on the process image being spawned, this
bit has no effect; otherwise, if not set, the child process will
inherit the effective group ID of the parent process, and if set, the
child process will inherit the real group ID of the parent process.
.It Dv POSIX_SPAWN_SETPGROUP
If this bit is not set, then the child process inherits the parent
process group; if set, then the child process shall behave as if the
.Xr setpgid 2
function had been called with a
.Fa pid
parameter of 0 and a
.Fa pgid
parameter equal to the value of the spawn-pgroup value of the
.Em posix_spawnattr_t ,
as set by
.Xr posix_spawnattr_setpgroup 3
.It Dv POSIX_SPAWN_SETSIGDEF
Signals set to to either be caught or to the default action in the
parent process will also be set to the default action in the child
process.  Signals set to be ignored in the parent process will be
ignored in the child.  However, if this bit is set, then signals in
the
.Em spawn-sigdefault
value of the
.Em posix_spawnattr_t ,
as set by
.Xr posix_spawnattr_setsigdefault 3
which are caught or ignored in the parent will instead be reset to
their default actions in the child.
.It Dv POSIX_SPAWN_SETSIGMASK
If this bit is set, then the initial signal mask of the child process will
be set to the
.Em spawn-sigmask
value of the
.Em posix_spawnattr_t ,
as set by
.Xr posix_spawnattr_setsigmask 3 .
.It Dv POSIX_SPAWN_SETEXEC
.Em Apple Extension :
If this bit is set, rather than returning to the caller,
.Xr posix_spawn 2
and
.Xr posix_spawnp 2
will behave as a more featureful
.Xr execve 2 .
.It Dv POSIX_SPAWN_START_SUSPENDED
.Em Apple Extension :
If this bit is set, then the child process will be created with its task
suspended, permitting debuggers, profilers, and other programs to
manipulate the process before it begins execution in user space.  This
permits, for example, obtaining exact instruction counts, or debugging
very early in
.Xr dyld 1 .
.El
.Sh RETURN VALUES
On success, these functions return 0; on failure they return an error
number from
.In errno.h .
The
.Fn posix_spawnattr_getflags
additionally, upon successful completion, modifies the value pointed to be the
.Fa attr
argument by making it equal to the
.Em spawn-flags
attribute of the
.Em posix_spawnattr_t .
.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_setpgroup 3 ,
.Xr posix_spawnattr_setsigdefault 3 ,
.Xr posix_spawnattr_setsigmask 3 ,
.Xr setpgid 2 ,
.Xr execve 2 ,
.Xr dyld 1
.Sh STANDARDS
.St -susv3 [SPN]
.Sh HISTORY
The
.Fn posix_spawnattr_setflags
and
.Fn posix_spawnattr_getflags
function calls appeared in
.St -susv3 [SPN] .