From ae14aa44a516ee901d3bb67086deb753c5769977 Mon Sep 17 00:00:00 2001
From: Colin Watson
Date: Thu, 28 Apr 2022 13:11:25 +0100
Subject: Add notes to libpipeline(3) of when functions were added
* man/libpipeline.3 (DESCRIPTION, ENVIRONMENT): Add various "Added in"
notes.
* NEWS.md: Document this.
---
NEWS.md | 5 +++++
man/libpipeline.3 | 31 +++++++++++++++++++++++++++++++
2 files changed, 36 insertions(+)
diff --git a/NEWS.md b/NEWS.md
index 61fde31..82bef5b 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,3 +1,8 @@
+libpipeline 1.5.7
+=================
+
+ * Add notes to libpipeline(3) of when functions were added.
+
libpipeline 1.5.6 (24 April 2022)
=================================
diff --git a/man/libpipeline.3 b/man/libpipeline.3
index cf19907..79feb23 100644
--- a/man/libpipeline.3
+++ b/man/libpipeline.3
@@ -186,6 +186,10 @@ command
.Sq echo foo bar
is counted as having three arguments.
.Pp
+Added in
+.Nm
+1.1.0.
+.Pp
.It Ft void Fn pipecmd_nice "pipecmd *cmd" "int value"
.Pp
Set the
@@ -210,6 +214,10 @@ Change the working directory to
.Va directory
while running this command.
.Pp
+Added in
+.Nm
+1.3.0.
+.Pp
.It Ft void Fn pipecmd_fchdir "pipecmd *cmd" "int directory_fd"
.Pp
Change the working directory to the directory given by the open file
@@ -217,6 +225,10 @@ descriptor
.Va directory_fd
while running this command.
.Pp
+Added in
+.Nm
+1.4.0.
+.Pp
.It Xo Ft void
.Fn pipecmd_setenv "pipecmd *cmd" "const char *name" "const char *value"
.Xc
@@ -243,6 +255,10 @@ Beware that this may cause unexpected failures, for example if some of the
contents of the environment are necessary to execute programs at all (say,
.Li PATH ) .
.Pp
+Added in
+.Nm
+1.1.0.
+.Pp
.It Xo Ft void
.Fo pipecmd_pre_exec
.Fa "pipecmd *cmd"
@@ -263,6 +279,10 @@ This is similar to pipeline_install_post_fork, except that is specific to a
single command rather than installing a global handler, and it runs slightly
later (immediately before exec rather than immediately after fork).
.Pp
+Added in
+.Nm
+1.5.0.
+.Pp
.It Ft void Fn pipecmd_sequence_command "pipecmd *cmd" "pipecmd *child"
.Pp
Add a command to a sequence created using
@@ -282,6 +302,10 @@ The caller should free the result.
Execute a single command, replacing the current process.
Never returns, instead exiting non-zero on failure.
.Pp
+Added in
+.Nm
+1.1.0.
+.Pp
.It Ft void Fn pipecmd_free "pipecmd *cmd"
.Pp
Destroy a command.
@@ -490,6 +514,10 @@ if
.Va n
is out of range or if the command has already exited and been reaped.
.Pp
+Added in
+.Nm
+1.2.0.
+.Pp
.It Ft "FILE *" Ns Fn pipeline_get_infile "pipeline *p"
.It Ft "FILE *" Ns Fn pipeline_get_outfile "pipeline *p"
.Pp
@@ -721,6 +749,9 @@ environment variable is set to any value, then
.Nm
will refrain from printing an error message when a subprocess is terminated
by a signal.
+Added in
+.Nm
+1.4.0.
.Sh EXAMPLES
In the following examples, function names starting with
.Li pipecmd_
--
cgit v1.2.3
From e95a2b5fa919726580bb6695c925ca7b0bfcf1ac Mon Sep 17 00:00:00 2001
From: Colin Watson
Date: Fri, 3 Jun 2022 12:29:08 +0100
Subject: Transferred Git repository to new group
* README.md: Change GitLab URL to
https://gitlab.com/libpipeline/libpipeline.
* NEWS.md: Document this.
---
NEWS.md | 1 +
README.md | 6 +++---
2 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/NEWS.md b/NEWS.md
index 82bef5b..91a419b 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -2,6 +2,7 @@ libpipeline 1.5.7
=================
* Add notes to libpipeline(3) of when functions were added.
+ * Transferred Git repository to https://gitlab.com/libpipeline/libpipeline.
libpipeline 1.5.6 (24 April 2022)
=================================
diff --git a/README.md b/README.md
index f84e222..fc2fd42 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# libpipeline, a pipeline manipulation library
-Git repository: https://gitlab.com/cjwatson/libpipeline
+Git repository: https://gitlab.com/libpipeline/libpipeline
libpipeline is a C library for setting up and running pipelines of
processes, without needing to involve shell command-line parsing which is
@@ -230,6 +230,6 @@ design review, and Kees Cook and Matthias Klose for helpful conversations.
## Bug reporting
You can [report bugs on
-GitLab](https://gitlab.com/cjwatson/libpipeline/-/issues), or see [bugs from
-before the migration to
+GitLab](https://gitlab.com/libpipeline/libpipeline/-/issues), or see [bugs
+from before the migration to
GitLab](https://savannah.nongnu.org/bugs/?group=libpipeline).
--
cgit v1.2.3
From 9c4efd8811fd12a275f80539c56e7fb8b59d0127 Mon Sep 17 00:00:00 2001
From: Colin Watson
Date: Fri, 3 Jun 2022 12:48:07 +0100
Subject: Add GitLab Pages site
* .gitlab-ci.yml (stages): Add deploy.
(pages): New job.
* web/index.html, web/libpipeline-lightning-talk.odp, web/standard.css,
web/white.css: New files.
---
.gitlab-ci.yml | 18 ++++
web/index.html | 179 +++++++++++++++++++++++++++++++++++++
web/libpipeline-lightning-talk.odp | Bin 0 -> 17004 bytes
web/standard.css | 133 +++++++++++++++++++++++++++
web/white.css | 2 +
5 files changed, 332 insertions(+)
create mode 100644 web/index.html
create mode 100644 web/libpipeline-lightning-talk.odp
create mode 100644 web/standard.css
create mode 100644 web/white.css
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 7eb1fcc..27fc5ac 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -5,6 +5,7 @@ variables:
GIT_DEPTH: 0
stages:
+ - deploy
- bootstrap
- build
- upload
@@ -24,6 +25,23 @@ pre-commit:
paths:
- .cache/pre-commit
+pages:
+ stage: deploy
+ before_script:
+ - apt -qq update
+ - apt -y -qq install bsdextrautils mandoc
+ script:
+ - rm -rf public
+ - cp -a web public
+ - mandoc -T ascii man/libpipeline.3 | col -b >public/libpipeline.3.txt
+ - mandoc -T html man/libpipeline.3 >public/libpipeline.3.html
+ artifacts:
+ paths:
+ - public
+ expire_in: 30 days
+ rules:
+ - if: $CI_COMMIT_BRANCH == "main"
+
bootstrap:
stage: bootstrap
before_script:
diff --git a/web/index.html b/web/index.html
new file mode 100644
index 0000000..cb442d7
--- /dev/null
+++ b/web/index.html
@@ -0,0 +1,179 @@
+
+
+
+
+libpipeline - pipeline manipulation library
+
+
+
+
+
+
+
+
+
+
libpipeline - pipeline manipulation library
+
+
Summary
+
+
libpipeline is a C library for manipulating pipelines of subprocesses in
+a flexible and convenient way. It is available in at least the following
+operating systems:
For macOS, you can install libpipeline using
+Homebrew with
+this "tap".
+
+
Description
+
+
When I took over man-db in 2001,
+one of the major problems that became evident after maintaining it for a
+while was the way it handled subprocesses. The nature of man and friends
+means that it spends a lot of time calling sequences of programs such as
+zsoelim < input-file | tbl | nroff -mandoc -Tutf8. Back then,
+it was using C library facilities such as system and
+popen for all this, and I had to deal with several bugs where
+those functions were being called with untrusted input as arguments without
+properly escaping metacharacters. Of course it was possible to chase around
+every such call inserting appropriate escaping functions, but this was
+always bound to be error-prone and one of the tasks that rapidly became
+important to me was arranging to start subprocesses in a way that was
+fundamentally immune to this kind of bug.
+
+
In higher-level languages, there are usually standard constructs which
+are safer than just passing a command line to the shell. For example, in
+Perl you can use system([$command, $arg1, $arg2, ...]) to
+invoke a program with arguments without the interference of the shell, and
+perlipc(1) describes various facilities for connecting them
+together. In Python, the
+subprocess
+module allows you to create pipelines easily and safely (as long as you
+remember the
+SIGPIPE
+gotcha). C has the fork and execve
+primitives, but assembling these to construct full-blown pipelines correctly
+is difficult and error-prone, so many programmers don't bother and use the
+simple but unsafe library facilities instead.
+
+
libpipeline solves this problem. In the following examples, function
+names starting with pipecmd_ or pipeline_ are real
+functions in the library, while any other function names are pseudocode.
+
+
Constructing the simplified example pipeline from my first paragraph
+using this library looks like this:
The libpipeline(3) manual page is available in
+HTML and
+text.
+
+
Installation
+
+
If your distribution includes a package of libpipeline, it's usually best
+to install that. However, if you need to install it starting from source
+code, then you will need these separate packages installed before
+configuring libpipeline in order to run its test suite:
For macOS, you can install libpipeline using
@@ -56,10 +54,10 @@ Perl you can use system([$command, $arg1, $arg2, ...]) to
invoke a program with arguments without the interference of the shell, and
perlipc(1) describes various facilities for connecting them
together. In Python, the
-subprocess
+subprocess
module allows you to create pipelines easily and safely (as long as you
remember the
-SIGPIPE
+SIGPIPE
gotcha). C has the fork and execve
primitives, but assembling these to construct full-blown pipelines correctly
is difficult and error-prone, so many programmers don't bother and use the
@@ -145,8 +143,6 @@ pipeline_free (p);