Re: [PATCH] posix: New function posix_spawn_file_actions_addchdir_np [BZ #17405]

[Carlos O'Donell <carlos at redhat dot com>]

On 10/30/18 1:50 AM, Florian Weimer wrote:
> * Carlos O'Donell:
> 
>> On 10/26/18 10:07 AM, Florian Weimer wrote:
>>> I'm not adding documentation in this patch because none exists for the
>>> posix_spawn functionality.
>>
>> We can do better though, I'm happy even if we just add the prototypes
>> into the manual to give others a place to hang more text in the future.
>> The safety notes would be helpful too, is it MT-safe, AS-safe etc.
>>
>> Would you please take a stab at adding something minimal?
> 
> I don't want to make *any* changes to the manual at this point, sorry.

Thanks. I appreciate the direct answer. I will try to take a stab at
some initial documentation for posix_spawn and posix_spawnp so that
we have somewhere to hang future changes.

For example:

diff --git a/manual/process.texi b/manual/process.texi
index b82b91f9f1..efa0bb8b14 100644
--- a/manual/process.texi
+++ b/manual/process.texi
@@ -34,6 +34,7 @@ primitive functions to do each step individually instead.
 * Process Identification::      How to get the process ID of a process.
 * Creating a Process::          How to fork a child process.
 * Executing a File::            How to make a process execute another program.
+* POSIX Spawn::			Combining fork and exec into spawn.
 * Process Completion::          How to tell when a child process has completed.
 * Process Completion Status::   How to interpret the status value
                                  returned from a child process.
@@ -497,6 +498,65 @@ they do not have @code{FD_CLOEXEC} set).  The new process image can
 reconnect these to new streams using @code{fdopen} (@pxref{Descriptors
 and Streams}).
 
+@node POSIX Spawn
+@section POSIX Spawn
+@cindex spawning a new process
+@cindex @code{posix_spawn} related functions
+
+The POSIX standard defines a set of functions which incorporate the
+common set of steps generally taken by @code{fork} and @code{exec}
+functions and puts them together into a portable set of APIs. These
+APIs allow the caller to @code{fork} a new process under the control
+of various options, carry out some pre-@code{exec} steps, and finally
+@code{exec} (again under the control of various options). The APIs
+
+@deftypefun int posix_spawn (pit_d *pid, const char *path,
+			     const posix_spawn_file_actions_t *file_actions,
+			     const posix_spawnattr_t *attrp,
+			     char *const argvp[], char *const envp[])
+
+Create a new child process by executing the @code{path} file. The
+execution of @code{path} follows three stages, first the @code{fork} stage,
+then the pre-@code{exec} stage, and lastly the @code{exec} stage. The actions
+taken at each step are described by the @code{posix_spawn_file_actions_t}
+and @code{posix_spawnattr_t} structures, with @code{argvp} and @code{envp}
+providing argument and environment pointers for the new child process.
+
+The @code{pid} pointer will contain the new PID of the child if
+execution is successful.
+@end deftypefun
+
+@deftypefun int posix_spawnp (pit_d *pid, const char *file,
+			      const posix_spawn_file_actions_t *file_actions,
+			      const posix_spawnattr_t *attrp,
+			      char *const argvp[], char *const envp[])
+
+Create a new child process by executing the @code{file} if it contains a
+slahs character, or the @code{PATH} environment variable will be
+searched for file. The execution of @code{path} follows three stages,
+first the @code{fork} stage, then the pre-@code{exec} stage, and lastly
+the @code{exec} stage. The actions taken at each step are described by
+the @code{posix_spawn_file_actions_t} and @code{posix_spawnattr_t}
+structures, with @code{argvp} and @code{envp} providing argument and
+environment pointers for the new child process.
+
+The @code{pid} pointer will contain the new PID of the child if
+execution is successful.
+@end deftypefun
+
+@section POSIX Spawn File Actions
+
+@section POSIX Spawn Attributes
+
+
+
+
+
+
+
+
+
+ 
 @node Process Completion
 @section Process Completion
 @cindex process completion
~~~

And then define the file actions, and spawn attributes.

Then add the funcitions themselves to get and set various properties.
* posix_spawn_file_actions_addclose
* posix_spawn_file_actions_adddup2
* posix_spawn_file_actions_addopen
* posix_spawn_file_actions_destroy
* posix_spawn_file_actions_init
* posix_spawnattr_destroy
* posix_spawnattr_getflags
* posix_spawnattr_getpgroup
* posix_spawnattr_getschedparam
* posix_spawnattr_getschedpolicy 
* posix_spawnattr_getsigdefault
* posix_spawnattr_getsigmask 
* posix_spawnattr_init 
* posix_spawnattr_setflags
* posix_spawnattr_setpgroup 
* posix_spawnattr_setschedparam
* posix_spawnattr_setschedpolicy 
* posix_spawnattr_setsigdefault
* posix_spawnattr_setsigmask

Is anything else required?

-- 
Cheers,
Carlos.