From: Bart Schaefer <schaefer@brasslantern.com>
To: Zsh hackers list <zsh-workers@zsh.org>
Subject: [PATCH] documentation and return status consistency in zsh/system module
Date: Wed, 8 Jun 2022 21:38:57 -0700 [thread overview]
Message-ID: <CAH+w=7bSXZOEy=T-8eaGcRTx++CF=2UAMQnh6Of7hSArF=HWfQ@mail.gmail.com> (raw)
[-- Attachment #1: Type: text/plain, Size: 89 bytes --]
Had this tucked away labeled to-do post-release. Trying to clean up
my local git clone.
[-- Attachment #2: zsystem.txt --]
[-- Type: text/plain, Size: 4453 bytes --]
diff --git a/Doc/Zsh/mod_system.yo b/Doc/Zsh/mod_system.yo
index 884c3e753..e25201faa 100644
--- a/Doc/Zsh/mod_system.yo
+++ b/Doc/Zsh/mod_system.yo
@@ -74,6 +74,11 @@ truncate file to size 0
)
enditem()
+A return status of 0 indicates the descriptor was successfully opened,
+otherwise an error message is printed, and 1 is returned for an error
+in the parameters to the command, or 2 is returned for a system error.
+The parameter tt(ERRNO) is nonzero for system errors.
+
To close the file, use one of the following:
example(tt(exec {)var(fd)tt(}<&-)
@@ -123,11 +128,11 @@ error for which a message is printed to standard error.
)
item(2)(
There was an error on the read, or on polling the input file descriptor
-for a timeout. The parameter tt(ERRNO) gives the error.
+for a timeout. The parameter tt(ERRNO) identifies the error.
)
item(3)(
Data were successfully read, but there was an error writing them
-to var(outfd). The parameter tt(ERRNO) gives the error.
+to var(outfd). The parameter tt(ERRNO) identifies the error.
)
item(4)(
The attempt to read timed out. Note this does not set tt(ERRNO) as this
@@ -147,6 +152,11 @@ expression. The tt(-u) option allows the file descriptor to be specified. By
default the offset is specified relative to the start or the file but, with the
tt(-w) option, it is possible to specify that the offset should be relative to
the current position or the end of the file.
+
+The return status may be 0 for success, 1 for an error in the parameters
+to the command, or 2 for an error on the seek; no error message is
+printed in the last case, but the parameter tt(ERRNO) reflects
+the error that occurred.
)
item(tt(syswrite) [ tt(-c) var(countvar) ] [ tt(-o) var(outfd) ] var(data))(
The data (a single string of bytes) are written to the file descriptor
@@ -166,7 +176,7 @@ returning early.
The return status may be 0 for success, 1 for an error in the parameters
to the command, or 2 for an error on the write; no error message is
-printed in the last case, but the parameter tt(ERRNO) will reflect
+printed in the last case, but the parameter tt(ERRNO) reflects
the error that occurred.
)
xitem(tt(zsystem flock) [ tt(-t) var(timeout) ] [ tt(-i) var(interval) ] [ tt(-f) var(var) ] [tt(-er)] var(file))
diff --git a/Src/Modules/system.c b/Src/Modules/system.c
index ea11ef037..929a8b002 100644
--- a/Src/Modules/system.c
+++ b/Src/Modules/system.c
@@ -74,6 +74,8 @@ bin_sysread(char *nam, char **args, Options ops, UNUSED(int func))
int infd = 0, outfd = -1, bufsize = SYSREAD_BUFSIZE, count;
char *outvar = NULL, *countvar = NULL, *inbuf;
+ errno = 0; /* Distinguish non-system errors */
+
/* -i: input file descriptor if not stdin */
if (OPT_ISSET(ops, 'i')) {
infd = getposint(OPT_ARG(ops, 'i'), nam);
@@ -238,6 +240,8 @@ bin_syswrite(char *nam, char **args, Options ops, UNUSED(int func))
int outfd = 1, len, count, totcount;
char *countvar = NULL;
+ errno = 0; /* Distinguish non-system errors */
+
/* -o: output file descriptor if not stdout */
if (OPT_ISSET(ops, 'o')) {
outfd = getposint(OPT_ARG(ops, 'o'), nam);
@@ -303,6 +307,13 @@ static struct { const char *name; int oflag; } openopts[] = {
{ "trunc", O_TRUNC }
};
+/*
+ * Return values of bin_sysopen:
+ * 0 Success
+ * 1 Error in parameters to command
+ * 2 Error on open, ERRNO set by system
+ */
+
/**/
static int
bin_sysopen(char *nam, char **args, Options ops, UNUSED(int func))
@@ -319,6 +330,8 @@ bin_sysopen(char *nam, char **args, Options ops, UNUSED(int func))
int fdflags = 0;
#endif
+ errno = 0; /* Distinguish non-system errors */
+
if (!OPT_ISSET(ops, 'u')) {
zwarnnam(nam, "file descriptor not specified");
return 1;
@@ -374,12 +387,12 @@ bin_sysopen(char *nam, char **args, Options ops, UNUSED(int func))
if (fd == -1) {
zwarnnam(nam, "can't open file %s: %e", *args, errno);
- return 1;
+ return 2;
}
moved_fd = (explicit > -1) ? redup(fd, explicit) : movefd(fd);
if (moved_fd == -1) {
zwarnnam(nam, "can't open file %s", *args);
- return 1;
+ return 2;
}
#ifdef FD_CLOEXEC
@@ -423,6 +436,8 @@ bin_sysseek(char *nam, char **args, Options ops, UNUSED(int func))
char *whence;
off_t pos;
+ errno = 0; /* Distinguish non-system errors */
+
/* -u: file descriptor if not stdin */
if (OPT_ISSET(ops, 'u')) {
fd = getposint(OPT_ARG(ops, 'u'), nam);
next reply other threads:[~2022-06-09 4:40 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-09 4:38 Bart Schaefer [this message]
2022-06-11 22:04 ` Bart Schaefer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAH+w=7bSXZOEy=T-8eaGcRTx++CF=2UAMQnh6Of7hSArF=HWfQ@mail.gmail.com' \
--to=schaefer@brasslantern.com \
--cc=zsh-workers@zsh.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.vuxu.org/mirror/zsh/
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).