[apple/xnu.git] / bsd / man / man3 / posix_spawn_file_actions_addclose.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_spawn_file_actions_addclose.3
.
.Dd August 22, 2007
.Dt POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE 3
.Os "Mac OS X"
.Sh NAME
.Nm posix_spawn_file_actions_addclose
.Nm posix_spawn_file_actions_addopen
.Nd add open or close actions to a
.Em posix_spawn_file_actions_t
.Sh SYNOPSIS
.Fd #include <spawn.h>
.Ft int
.Fo posix_spawn_file_actions_addclose
.Fa "posix_spawn_file_actions_t *file_actions"
.Fa "int filedes"
.Fc
.Ft int
.Fo posix_spawn_file_actions_addopen
.Fa "posix_spawn_file_actions_t *restrict file_actions"
.Fa "int filedes"
.Fa "const char *restrict path"
.Fa "int oflag"
.Fa "mode_t mode"
.Fc
.Ft int
.Fo posix_spawn_file_actions_adddup2
.Fa "posix_spawn_file_actions_t *file_actions"
.Fa "int filedes"
.Fa "int newfiledes"
.Fc
.Sh DESCRIPTION
The
.Fn posix_spawn_file_actions_addclose
function adds a close operation to the list of operations associated with
the object referenced by
.Em file_actions ,
for subsequent use in a call to
.Xr posix_spawn 2
or 
.Xr posix_spawnp 2 .
The descriptor referred to by
.Em filedes
is closed as if
.Fn close
had been called on it prior to the new child process
starting execution.
.Pp
The
.Fn posix_spawn_file_actions_addopen
function adds an open operation to the list of operations associated with
the object referenced by
.Em file_actions ,
for subsequent use in a call to
.Xr posix_spawn 2
or 
.Xr posix_spawnp 2 .
The descriptor referred to by
.Em filedes
is opened using the
.Em path ,
.Em oflag ,
and
.Em mode
arguments as if
.Fn open
had been called on it prior to the new child process
starting execution.  The string
.Em path
is copied by the
.Fn posix_spawn_file_actions_addopen
function during this process, so storage need not be persistent in the
caller.
.Pp
The
.Fn posix_spawn_file_actions_adddup2
function adds a dup2 operation to the list of operations associated with
the object referenced by
.Em file_actions ,
for subsequent use in a call to
.Xr posix_spawn 2
or 
.Xr posix_spawnp 2 .
The descriptor referred to by
.Em newfiledes
is created as if
.Fn dup2
had been called on
.Em filedes
prior to the new child process starting execution.
.Sh RETURN VALUES
On success, these functions return 0; on failure they return an error
number from
.In errno.h .
.Sh ERRORS
These functions may fail if:
.Bl -tag -width Er
.\" ==========
.It Bq Er EBADF
The value specified by
.Fa filedes
is negative or would cause the process to exceed the maximum number of
open files it is allowed..
.\" ==========
.It Bq Er EINVAL
The value of
.Fa file_actions
is invalid.
.\" ==========
.It Bq Er ENOMEM
Insufficient memory was available eo add to the
.Fa file_actions .
.El
.Sh SEE ALSO
.Xr posix_spawn 2 ,
.Xr posix_spawnp 2 ,
.Xr posix_spawn_file_actions_init 3 ,
.Xr posix_spawn_file_actions_destroy 3 ,
.Sh STANDARDS
.St -susv3 [SPN]
.Sh HISTORY
The
.Fn posix_spawn_file_actions_init
and
.Fn posix_spawn_file_actions_destroy
function calls appeared in
.St -susv3 [SPN] .
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_spawn_file_actions_addclose.3
	29	.
	30	.Dd August 22, 2007
	31	.Dt POSIX_SPAWN_FILE_ACTIONS_ADDCLOSE 3
	32	.Os "Mac OS X"
	33	.Sh NAME
	34	.Nm posix_spawn_file_actions_addclose
	35	.Nm posix_spawn_file_actions_addopen
	36	.Nd add open or close actions to a
	37	.Em posix_spawn_file_actions_t
	38	.Sh SYNOPSIS
	39	.Fd #include <spawn.h>
	40	.Ft int
	41	.Fo posix_spawn_file_actions_addclose
	42	.Fa "posix_spawn_file_actions_t *file_actions"
	43	.Fa "int filedes"
	44	.Fc
	45	.Ft int
	46	.Fo posix_spawn_file_actions_addopen
	47	.Fa "posix_spawn_file_actions_t *restrict file_actions"
	48	.Fa "int filedes"
	49	.Fa "const char *restrict path"
	50	.Fa "int oflag"
	51	.Fa "mode_t mode"
	52	.Fc
	53	.Ft int
	54	.Fo posix_spawn_file_actions_adddup2
	55	.Fa "posix_spawn_file_actions_t *file_actions"
	56	.Fa "int filedes"
	57	.Fa "int newfiledes"
	58	.Fc
	59	.Sh DESCRIPTION
	60	The
	61	.Fn posix_spawn_file_actions_addclose
	62	function adds a close operation to the list of operations associated with
	63	the object referenced by
	64	.Em file_actions ,
65	for subsequent use in a call to
66	.Xr posix_spawn 2
67	or
68	.Xr posix_spawnp 2 .
69	The descriptor referred to by
70	.Em filedes
71	is closed as if
72	.Fn close
73	had been called on it prior to the new child process
74	starting execution.
75	.Pp
76	The
77	.Fn posix_spawn_file_actions_addopen
78	function adds an open operation to the list of operations associated with
79	the object referenced by
80	.Em file_actions ,
81	for subsequent use in a call to
82	.Xr posix_spawn 2
83	or
84	.Xr posix_spawnp 2 .
85	The descriptor referred to by
86	.Em filedes
87	is opened using the
88	.Em path ,
89	.Em oflag ,
90	and
91	.Em mode
92	arguments as if
93	.Fn open
94	had been called on it prior to the new child process
95	starting execution. The string
96	.Em path
97	is copied by the
98	.Fn posix_spawn_file_actions_addopen
99	function during this process, so storage need not be persistent in the
100	caller.
101	.Pp
102	The
103	.Fn posix_spawn_file_actions_adddup2
104	function adds a dup2 operation to the list of operations associated with
105	the object referenced by
106	.Em file_actions ,
107	for subsequent use in a call to
108	.Xr posix_spawn 2
109	or
110	.Xr posix_spawnp 2 .
111	The descriptor referred to by
112	.Em newfiledes
113	is created as if
114	.Fn dup2
115	had been called on
116	.Em filedes
117	prior to the new child process starting execution.
118	.Sh RETURN VALUES
119	On success, these functions return 0; on failure they return an error
120	number from
121	.In errno.h .
122	.Sh ERRORS
123	These functions may fail if:
124	.Bl -tag -width Er
125	.\" ==========
126	.It Bq Er EBADF
127	The value specified by
128	.Fa filedes
129	is negative or would cause the process to exceed the maximum number of
130	open files it is allowed..
131	.\" ==========
132	.It Bq Er EINVAL
133	The value of
134	.Fa file_actions
135	is invalid.
136	.\" ==========
137	.It Bq Er ENOMEM
138	Insufficient memory was available eo add to the
139	.Fa file_actions .
140	.El
141	.Sh SEE ALSO
142	.Xr posix_spawn 2 ,
143	.Xr posix_spawnp 2 ,
144	.Xr posix_spawn_file_actions_init 3 ,
145	.Xr posix_spawn_file_actions_destroy 3 ,
146	.Sh STANDARDS
147	.St -susv3 [SPN]
148	.Sh HISTORY
149	The
150	.Fn posix_spawn_file_actions_init
151	and
152	.Fn posix_spawn_file_actions_destroy
153	function calls appeared in
154	.St -susv3 [SPN] .