1.\"	$OpenBSD: posix_spawn_file_actions_addopen.3,v 1.9 2022/03/29 18:15:52 naddy Exp $
2.\"
3.\" Copyright (c) 2012 Marc Espie <espie@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: March 29 2022 $
18.Dt POSIX_SPAWN_FILE_ACTIONS_ADDOPEN 3
19.Os
20.Sh NAME
21.Nm posix_spawn_file_actions_addclose ,
22.Nm posix_spawn_file_actions_adddup2 ,
23.Nm posix_spawn_file_actions_addopen
24.Nd add action to close, dup2 or open file descriptor to file actions object
25.Sh SYNOPSIS
26.In spawn.h
27.Ft int
28.Fn posix_spawn_file_actions_addclose "posix_spawn_file_actions_t *file_actions" "int fildes"
29.Ft int
30.Fn posix_spawn_file_actions_adddup2 "posix_spawn_file_actions_t *file_actions" "int fildes" "int newfildes"
31.Ft int
32.Fn posix_spawn_file_actions_addopen "posix_spawn_file_actions_t *file_actions" "int fildes" "const char *restrict path" "int oflag" "mode_t mode"
33.Sh DESCRIPTION
34These function add an action to
35.Xr close 2 ,
36.Xr dup2 2 ,
37or
38.Xr open 2
39a file descriptor
40to a
41.Xr posix_spawn 3
42file actions object.
43.Pp
44Actions are executed in order in the child process:
45.Bl -dash
46.It
47The
48.Fn posix_spawn_file_actions_addclose
49function adds an action that causes
50.Bd -literal -offset indent
51close(fildes);
52.Ed
53.Pp
54to be called.
55.It
56The
57.Fn posix_spawn_file_actions_adddup2
58function adds an action that causes
59.Bd -literal -offset indent
60dup2(fildes, newfildes);
61.Ed
62.Pp
63to be called.
64In addition, the action will cause the close-on-exec flag to be cleared on
65.Fa newfildes ,
66even if
67.Fa newfildes
68equals
69.Fa fildes .
70.It
71The
72.Fn posix_spawn_file_actions_addopen
73function adds an action that causes
74.Bd -literal -offset indent
75open(path, oflag, mode);
76.Ed
77.Pp
78to be called and the result to be forced as
79.Fa fildes
80(if
81.Fa fildes
82was already open before this action, the old file descriptor
83is closed before the action is performed).
84.Pp
85Note that
86.Fn posix_spawn_file_actions_addopen
87makes a copy of the
88.Fa path
89argument.
90.El
91.Sh RETURN VALUES
92Upon successful completion, these functions return zero.
93Otherwise they may return
94.Er EINVAL
95for negative file descriptors, or
96.Er ENOMEM
97if they run out of memory.
98.Sh SEE ALSO
99.Xr posix_spawn 3 ,
100.Xr posix_spawn_file_actions_init 3 ,
101.Xr posix_spawnp 3
102.Sh STANDARDS
103These functions conform to
104.St -p1003.1-2001 .
105.Sh AUTHORS
106.An \&Ed Schouten Aq Mt ed@FreeBSD.org
107