From patchwork Thu Nov 1 02:03:26 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Carlos O'Donell X-Patchwork-Id: 29990 Received: (qmail 129377 invoked by alias); 1 Nov 2018 02:03:35 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 129208 invoked by uid 89); 1 Nov 2018 02:03:34 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-23.3 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_LAZY_DOMAIN_SECURITY, KAM_LINEPADDING, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.2 spammy=Identification X-HELO: mail-qt1-f194.google.com Return-Path: Subject: Re: [PATCH] posix: New function posix_spawn_file_actions_addchdir_np [BZ #17405] To: Florian Weimer Cc: libc-alpha@sourceware.org References: <87zhv0g5t3.fsf@oldenburg.str.redhat.com> <87ftwooue2.fsf@oldenburg.str.redhat.com> From: Carlos O'Donell Openpgp: preference=signencrypt Message-ID: <2ee55960-100c-ca37-1b5a-2b572054d113@redhat.com> Date: Wed, 31 Oct 2018 22:03:26 -0400 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.2.1 MIME-Version: 1.0 In-Reply-To: <87ftwooue2.fsf@oldenburg.str.redhat.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: ~~~ 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? 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