From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp3.mail.ru (smtp3.mail.ru [94.100.179.58]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by dev.tarantool.org (Postfix) with ESMTPS id 672744696CB for ; Tue, 14 Apr 2020 14:38:57 +0300 (MSK) From: Alexander Turenko Date: Tue, 14 Apr 2020 14:38:18 +0300 Message-Id: <9c95d9dbd375121060090b71e8243a57c4f3ee89.1586862436.git.alexander.turenko@tarantool.org> In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [Tarantool-patches] [PATCH 09/12] popen: clarify popen_{signal, delete} contract List-Id: Tarantool development patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Cyrill Gorcunov Cc: tarantool-patches@dev.tarantool.org It is convenient to have a formal description of an API during development and when writing a documentation. I plan to use those contracts when I will write an API description for the future popen Lua module. Part of #4031 --- src/lib/core/popen.c | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/src/lib/core/popen.c b/src/lib/core/popen.c index 1733e5131..411aad03b 100644 --- a/src/lib/core/popen.c +++ b/src/lib/core/popen.c @@ -360,7 +360,7 @@ popen_write_timeout(struct popen_handle *handle, const void *buf, * * - IllegalParams: a parameter check fails: * - count: buffer is too big. - * - flags: POPEN_FLAG_FD_STD{OUT,ERR} are unset both. + * - flags: POPEN_FLAG_FD_STD{OUT,ERR} are set or unset both. * - handle: handle does not support the requested IO operation. * - SocketError: an IO error occurs at read(). * - TimedOut: @a timeout quota is exceeded. @@ -536,8 +536,18 @@ popen_state_str(unsigned int state) /** * Send a signal to a child process. * + * When POPEN_FLAG_GROUP_SIGNAL is set the function sends + * a signal to a process group rather than a process. + * * Return 0 at success or -1 at failure (and set a diag). * + * Possible errors: + * + * - SystemError: a process does not exists anymore + * - SystemError: invalid signal number + * - SystemError: no permission to send a signal to + * a process or a process group + * * Set errno to ESRCH when a process does not exist. */ int @@ -578,9 +588,21 @@ popen_send_signal(struct popen_handle *handle, int signo) /** * Delete a popen handle. * - * The function kills a child process and - * close all fds and remove the handle from - * a living list and finally frees the handle. + * The function performs the following actions: + * + * - Kill a child process or a process group depending of + * POPEN_FLAG_GROUP_SIGNAL (if the process is alive and + * POPEN_FLAG_KEEP_CHILD flag is not set). + * - Close all fds occupied by the handle. + * - Remove the handle from a living list. + * - Free all occupied memory. + * + * Return 0 at success and -1 at failure (and set a diag). + * + * Possible errors: + * + * - SystemError: no permission to send a signal to + * a process or a process group */ int popen_delete(struct popen_handle *handle) -- 2.25.0