├── man1 ├── homeof.1 ├── define.1 ├── piperw.1 ├── fdswap.1 ├── exit.1 ├── fdclose.1 ├── export.1 ├── unexport.1 ├── execline-shell.1 ├── background.1 ├── execline-umask.1 ├── heredoc.1 ├── fdblock.1 ├── execline-cd.1 ├── ifelse.1 ├── getpid.1 ├── execline-startup.1 ├── ifthenelse.1 ├── exec.1 ├── getcwd.1 ├── loopwhilex.1 ├── ifte.1 ├── foreground.1 ├── pipeline.1 ├── fdmove.1 ├── tryexec.1 ├── elgetopt.1 ├── emptyenv.1 ├── shift.1 ├── elglob.1 ├── if.1 ├── posix-cd.1 ├── fdreserve.1 ├── runblock.1 ├── posix-umask.1 ├── withstdinas.1 ├── importas.1 ├── dollarat.1 ├── forx.1 ├── backtick.1 ├── multidefine.1 ├── elgetpositionals.1 ├── execline.1 ├── wait.1 ├── multisubstitute.1 ├── redirfd.1 ├── forstdin.1 ├── envfile.1 ├── forbacktickx.1 ├── trap.1 ├── case.1 ├── eltest.1 └── execlineb.1 ├── LICENSE ├── README.md ├── Makefile └── man7 ├── execline-components.7 ├── execline-exitcodes.7 ├── execline-block.7 ├── execline-pushenv.7 ├── execline-grammar.7 ├── execline-transform.7 └── execline-substitute.7 /man1/homeof.1: -------------------------------------------------------------------------------- 1 | .Dd February 11, 2021 2 | .Dt HOMEOF 1 3 | .Os 4 | .Sh NAME 5 | .Nm homeof 6 | .Nd print the home directory of a user 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar user 10 | .Sh DESCRIPTION 11 | .Nm 12 | finds the name of 13 | .Ar user Ap 14 | s home directory, writes it on stdout, then exits 0. 15 | If an error occurs, it prints nothing on stdout but exits 111 with an 16 | explanatory message on stderr. 17 | .Sh SEE ALSO 18 | This man page is ported from the authoritative documentation at: 19 | .Lk https://skarnet.org/software/execline/homeof.html 20 | .Sh AUTHORS 21 | .An Laurent Bercot 22 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 23 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2011-2023 Laurent Bercot 2 | Copyright (c) 2021-2023 Alexis 3 | 4 | Permission to use, copy, modify, and distribute this software for any 5 | purpose with or without fee is hereby granted, provided that the above 6 | copyright notice and this permission notice appear in all copies. 7 | 8 | THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9 | WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10 | MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11 | ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13 | ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14 | OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | ## NOTE: This repository is now read-only - official repository now at https://git.sr.ht/~flexibeast/execline-man-pages 3 | 4 | This repository provides [mdoc(7)](https://man.openbsd.org/mdoc.7) 5 | ports of the HTML documentation for the [execline 6 | suite](http://skarnet.org/software/execline/). The HTML version 7 | on the execline site is authoritative; in the event of semantic 8 | differences between an HTML original and its port, please open an 9 | issue in this repository. 10 | 11 | To install the man pages, run `make`. 12 | 13 | The default installation directory is `/usr/share/man`, but this can 14 | be changed by setting the `MAN_DIR` environment variable prior to 15 | running `make`. The user running `make` will need to have the 16 | appropriate permissions for installation in the chosen directory. 17 | 18 | The man pages can be uninstalled by running `make uninstall`. 19 | 20 | HTML versions can be produced with 21 | [mandoc(1)](https://man.openbsd.org/mandoc.1)'s `-T` flag: 22 | 23 | ``` 24 | $ mandoc -T html man1/background.1 > background.1.html 25 | ``` 26 | -------------------------------------------------------------------------------- /man1/define.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt DEFINE 1 3 | .Os 4 | .Sh NAME 5 | .Nm define 6 | .Nd replace a literal with a value, then execute another program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl s 10 | .Op Fl C | Fl c 11 | .Op Fl N | Fl n 12 | .Op Fl d Ar delim 13 | .Ar variable 14 | .Ar value 15 | .Ar prog.. 16 | .Sh DESCRIPTION 17 | .Nm 18 | performs substitution 19 | .Po 20 | cf.\& 21 | .Xr execline-substitute 7 22 | .Pc 23 | on 24 | .Ar prog... , 25 | using 26 | .Ar variable 27 | as key and 28 | .Ar value 29 | as value. 30 | .Pp 31 | .Nm Ap 32 | s options are used to control the substitution mechanism; refer to 33 | .Xr execline-transform 7 . 34 | .Pp 35 | .Nm 36 | then execs into the modified 37 | .Ar prog... . 38 | .Sh SEE ALSO 39 | .Xr elgetpositionals 1 , 40 | .Xr elglob 1 , 41 | .Xr importas 1 , 42 | .Xr multidefine 1 , 43 | .Xr multisubstitute 1 , 44 | .Xr execline-substitute 7 , 45 | .Xr execline-transform 7 46 | .Pp 47 | This man page is ported from the authoritative documentation at: 48 | .Lk https://skarnet.org/software/execline/define.html 49 | .Sh AUTHORS 50 | .An Laurent Bercot 51 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 52 | -------------------------------------------------------------------------------- /man1/piperw.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt PIPERW 1 3 | .Os 4 | .Sh NAME 5 | .Nm piperw 6 | .Nd create a pipe (an anonymous one), then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar fdr 10 | .Ar fdw 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | creates a pipe with descriptor 15 | .Ar fdw 16 | as the writing end and descriptor 17 | .Ar fdr 18 | as the reading end. 19 | It then execs into 20 | .Ar prog 21 | with its arguments. 22 | .Sh SEE ALSO 23 | .Xr emptyenv 1 , 24 | .Xr envfile 1 , 25 | .Xr exec 1 , 26 | .Xr execline-cd 1 , 27 | .Xr execline-umask 1 , 28 | .Xr exit 1 , 29 | .Xr export 1 , 30 | .Xr fdblock 1 , 31 | .Xr fdclose 1 , 32 | .Xr fdmove 1 , 33 | .Xr fdreserve 1 , 34 | .Xr fdswap 1 , 35 | .Xr getcwd 1 , 36 | .Xr getpid 1 , 37 | .Xr heredoc 1 , 38 | .Xr posix-cd 1 , 39 | .Xr posix-umask 1 , 40 | .Xr redirfd 1 , 41 | .Xr trap 1 , 42 | .Xr tryexec 1 , 43 | .Xr unexport 1 , 44 | .Xr wait 1 , 45 | .Xr withstdinas 1 46 | .Pp 47 | This man page is ported from the authoritative documentation at: 48 | .Lk https://skarnet.org/software/execline/piperw.html 49 | .Sh AUTHORS 50 | .An Laurent Bercot 51 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 52 | -------------------------------------------------------------------------------- /man1/fdswap.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt FDSWAP 1 3 | .Os 4 | .Sh NAME 5 | .Nm fdswap 6 | .Nd swap two file descriptors, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar fd1 10 | .Ar fd2 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | swaps file descriptors numbered 15 | .Ar fd1 16 | and 17 | .Ar fd2 , then 18 | .Xr exec 3 Ns 19 | s into 20 | .Ar prog 21 | with its arguments. 22 | .Pp 23 | .Nm 24 | has no portable shell equivalent. 25 | .Sh SEE ALSO 26 | .Xr emptyenv 1 , 27 | .Xr envfile 1 , 28 | .Xr exec 1 , 29 | .Xr execline-cd 1 , 30 | .Xr execline-umask 1 , 31 | .Xr exit 1 , 32 | .Xr export 1 , 33 | .Xr fdblock 1 , 34 | .Xr fdclose 1 , 35 | .Xr fdmove 1 , 36 | .Xr fdreserve 1 , 37 | .Xr getcwd 1 , 38 | .Xr getpid 1 , 39 | .Xr heredoc 1 , 40 | .Xr piperw 1 , 41 | .Xr posix-cd 1 , 42 | .Xr posix-umask 1 , 43 | .Xr redirfd 1 , 44 | .Xr trap 1 , 45 | .Xr tryexec 1 , 46 | .Xr unexport 1 , 47 | .Xr wait 1 , 48 | .Xr withstdinas 1 , 49 | .Xr exec 3 50 | .Pp 51 | This man page is ported from the authoritative documentation at: 52 | .Lk https://skarnet.org/software/execline/fdswap.html 53 | .Sh AUTHORS 54 | .An Laurent Bercot 55 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 56 | -------------------------------------------------------------------------------- /man1/exit.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EXIT 1 3 | .Os 4 | .Sh NAME 5 | .Nm exit 6 | .Nd exit with a given exit code 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Ar n 10 | .Sh DESCRIPTION 11 | .Nm 12 | exits with the exit code 13 | .Ar n , 14 | or 0 if 15 | .Ar n 16 | is not given (in which case it's the same as 17 | .Ql true 18 | ). 19 | If 20 | .Ar n 21 | is not a number, 22 | .Nm 23 | exits 100. 24 | .Pp 25 | .Ql exit 26 | is a standard shell builtin, with the same function. 27 | .Sh SEE ALSO 28 | .Xr emptyenv 1 , 29 | .Xr envfile 1 , 30 | .Xr exec 1 , 31 | .Xr execline-cd 1 , 32 | .Xr execline-umask 1 , 33 | .Xr export 1 , 34 | .Xr fdblock 1 , 35 | .Xr fdclose 1 , 36 | .Xr fdmove 1 , 37 | .Xr fdreserve 1 , 38 | .Xr fdswap 1 , 39 | .Xr getcwd 1 , 40 | .Xr getpid 1 , 41 | .Xr heredoc 1 , 42 | .Xr piperw 1 , 43 | .Xr posix-cd 1 , 44 | .Xr posix-umask 1 , 45 | .Xr redirfd 1 , 46 | .Xr trap 1 , 47 | .Xr tryexec 1 , 48 | .Xr unexport 1 , 49 | .Xr wait 1 , 50 | .Xr withstdinas 1 51 | .Pp 52 | This man page is ported from the authoritative documentation at: 53 | .Lk https://skarnet.org/software/execline/exit.html 54 | .Sh AUTHORS 55 | .An Laurent Bercot 56 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 57 | -------------------------------------------------------------------------------- /man1/fdclose.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt FDCLOSE 1 3 | .Os 4 | .Sh NAME 5 | .Nm fdclose 6 | .Nd 7 | close a given file descriptor, then execute a program 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Ar fd 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | closes the file descriptor number 15 | .Ar fd , 16 | then 17 | .Xr exec 3 Ns 18 | s into 19 | .Ar prog 20 | with its arguments. 21 | .Pp 22 | .Ql fdclose Ar n Ar prog... 23 | is roughly equivalent to 24 | .Ql sh -c 'exec Ar prog... Ar n Ns <&-' 25 | .Sh SEE ALSO 26 | .Xr emptyenv 1 , 27 | .Xr envfile 1 , 28 | .Xr exec 1 , 29 | .Xr execline-cd 1 , 30 | .Xr execline-umask 1 , 31 | .Xr exit 1 , 32 | .Xr export 1 , 33 | .Xr fdblock 1 , 34 | .Xr fdmove 1 , 35 | .Xr fdreserve 1 , 36 | .Xr fdswap 1 , 37 | .Xr getcwd 1 , 38 | .Xr getpid 1 , 39 | .Xr heredoc 1 , 40 | .Xr piperw 1 , 41 | .Xr posix-cd 1 , 42 | .Xr posix-umask 1 , 43 | .Xr redirfd 1 , 44 | .Xr trap 1 , 45 | .Xr tryexec 1 , 46 | .Xr unexport 1 , 47 | .Xr wait 1 , 48 | .Xr withstdinas 1 , 49 | .Xr exec 3 50 | .Pp 51 | This man page is ported from the authoritative documentation at: 52 | .Lk https://skarnet.org/software/execline/fdclose.html 53 | .Sh AUTHORS 54 | .An Laurent Bercot 55 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 56 | -------------------------------------------------------------------------------- /man1/export.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EXPORT 1 3 | .Os 4 | .Sh NAME 5 | .Nm export 6 | .Nd set an environment variable to a given value, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar var 10 | .Ar value 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | sets the 15 | .Ar var 16 | environment variable to the string 17 | .Ar value , 18 | then execs into 19 | .Ar prog 20 | with its arguments. 21 | .Pp 22 | .Ar var 23 | must be given without a dollar! 24 | .Pp 25 | .Ar var 26 | must not contain the character 27 | .Ql = . 28 | .Sh SEE ALSO 29 | .Xr emptyenv 1 , 30 | .Xr envfile 1 , 31 | .Xr exec 1 , 32 | .Xr execline-cd 1 , 33 | .Xr execline-umask 1 , 34 | .Xr exit 1 , 35 | .Xr fdblock 1 , 36 | .Xr fdclose 1 , 37 | .Xr fdmove 1 , 38 | .Xr fdreserve 1 , 39 | .Xr fdswap 1 , 40 | .Xr getcwd 1 , 41 | .Xr getpid 1 , 42 | .Xr heredoc 1 , 43 | .Xr piperw 1 , 44 | .Xr posix-cd 1 , 45 | .Xr posix-umask 1 , 46 | .Xr redirfd 1 , 47 | .Xr trap 1 , 48 | .Xr tryexec 1 , 49 | .Xr unexport 1 , 50 | .Xr wait 1 , 51 | .Xr withstdinas 1 52 | .Pp 53 | This man page is ported from the authoritative documentation at: 54 | .Lk https://skarnet.org/software/execline/export.html 55 | .Sh AUTHORS 56 | .An Laurent Bercot 57 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 58 | -------------------------------------------------------------------------------- /man1/unexport.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt UNEXPORT 1 3 | .Os 4 | .Sh NAME 5 | .Nm unexport 6 | .Nd remove a variable from the environment, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar var 10 | .Ar prog... 11 | .Sh DESCRIPTION 12 | .Nm 13 | removes the 14 | .Ar var 15 | variable from the environment, then 16 | .Xr exec 3 Ns 17 | s into 18 | .Ar prog 19 | with its arguments. 20 | .Pp 21 | Unsetting 22 | .Ar var 23 | is quite different from setting it to an empty value. 24 | Shell scripts usually won't make the distinction; execline does. 25 | .Sh SEE ALSO 26 | .Xr emptyenv 1 , 27 | .Xr envfile 1 , 28 | .Xr exec 1 , 29 | .Xr execline-cd 1 , 30 | .Xr execline-umask 1 , 31 | .Xr exit 1 , 32 | .Xr export 1 , 33 | .Xr fdblock 1 , 34 | .Xr fdclose 1 , 35 | .Xr fdmove 1 , 36 | .Xr fdreserve 1 , 37 | .Xr fdswap 1 , 38 | .Xr getcwd 1 , 39 | .Xr getpid 1 , 40 | .Xr heredoc 1 , 41 | .Xr piperw 1 , 42 | .Xr posix-cd 1 , 43 | .Xr posix-umask 1 , 44 | .Xr redirfd 1 , 45 | .Xr trap 1 , 46 | .Xr tryexec 1 , 47 | .Xr wait 1 , 48 | .Xr withstdinas 1 , 49 | .Xr exec 3 50 | .Pp 51 | This man page is ported from the authoritative documentation at: 52 | .Lk https://skarnet.org/software/execline/unexport.html 53 | .Sh AUTHORS 54 | .An Laurent Bercot 55 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 56 | -------------------------------------------------------------------------------- /man1/execline-shell.1: -------------------------------------------------------------------------------- 1 | .Dd February 16, 2021 2 | .Dt EXECLINE-SHELL 1 3 | .Os 4 | .Sh NAME 5 | .Nm execline-shell 6 | .Nd execute 7 | .Pa $HOME/.execline-shell 8 | if available (or 9 | .Pa /bin/sh 10 | otherwise) with the arguments given 11 | .Sh SYNOPSIS 12 | .Pa /etc/execline-shell 13 | .Sh DESCRIPTION 14 | .Nm 15 | transforms itself into 16 | .Ql ${HOME}/.execline-shell $@ . 17 | .Pp 18 | .Pa ${HOME}/.execline-shell 19 | must be readable and executable by the user. 20 | It must 21 | .Xr exec 3 22 | into an interactive shell with 23 | .Ql $@ 24 | as its argument. 25 | .Pp 26 | .Nm 27 | is meant to be used as the 28 | .Ev SHELL 29 | environment variable value. 30 | It allows one to specify their favourite shell and shell configuration 31 | in any language, since the 32 | .Pa ${HOME}/.execline-shell 33 | file can be any executable program. 34 | .Pa ${HOME}/.execline-shell 35 | can be seen as a portable 36 | .Ql . Ns Ar whatever Ns rc 37 | file. 38 | .Pp 39 | As an administrator-modifiable configuration file, 40 | .Pa execline-shell 41 | is provided in execline's 42 | .Pa examples/etc/ 43 | subdirectory, and should be copied by the administrator to 44 | .Pa /etc . 45 | .Sh SEE ALSO 46 | .Xr exec 3 47 | .Pp 48 | This man page is ported from the authoritative documentation at: 49 | .Lk https://skarnet.org/software/execline/execline-shell.html 50 | .Sh AUTHORS 51 | .An Laurent Bercot 52 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 53 | -------------------------------------------------------------------------------- /man1/background.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt BACKGROUND 1 3 | .Os 4 | .Sh NAME 5 | .Nm background 6 | .Nd launch a command in the background, then go on with the execution flow 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl d 14 | { 15 | .Ar prog1... 16 | } 17 | .Ar prog2... 18 | .Sh DESCRIPTION 19 | .Nm 20 | reads a 21 | .Ar prog1... 22 | command in an 23 | .Xr execline-block 7 24 | and unquotes it. 25 | .Pp 26 | It spawns a child executing 27 | .Ar prog1... . 28 | .Pp 29 | It sets the 30 | .Ev \&! 31 | environment variable to the pid of the 32 | .Ar prog1... 33 | process. 34 | .Pp 35 | It then 36 | .Xr exec 3 Ns 37 | s into 38 | .Ar prog2... . 39 | .Pp 40 | The command: 41 | .Bd -literal -offset indent 42 | background prog1... \(dq\(dq prog2... 43 | .Ed 44 | .Pp 45 | is equivalent to: 46 | .Bd -literal -offset indent 47 | sh -c 'prog1... & ; exec prog2...' 48 | .Ed 49 | .Sh OPTIONS 50 | .Bl -tag -width x 51 | .It Fl d 52 | Doublefork. 53 | If the 54 | .Fl d 55 | option is set, 56 | .Ar prog1... 57 | will run as a grandchild of 58 | .Nm . 59 | .El 60 | .Sh SEE ALSO 61 | .Xr backtick 1 , 62 | .Xr foreground 1 , 63 | .Xr if 1 , 64 | .Xr ifelse 1 , 65 | .Xr ifte 1 , 66 | .Xr ifthenelse 1 , 67 | .Xr pipeline 1 , 68 | .Xr runblock 1 , 69 | .Xr execline-block 7 70 | .Pp 71 | This man page is ported from the authoritative documentation at: 72 | .Lk https://skarnet.org/software/execline/background.html 73 | .Sh AUTHORS 74 | .An Laurent Bercot 75 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 76 | -------------------------------------------------------------------------------- /man1/execline-umask.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EXECLINE-UMASK 1 3 | .Os 4 | .Sh NAME 5 | .Nm execline-umask 6 | .Nd set the umask (file creation mask), then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar mask 10 | .Ar prog... 11 | .Sh DESCRIPTION 12 | .Nm 13 | sets the current umask to 14 | .Ar mask , 15 | then 16 | .Xr exec 3 Ns 17 | s into 18 | .Ar prog... . 19 | By default, at execline installation time, a 20 | .Pa umask 21 | symbolic link is created, pointing to 22 | .Pa execline-umask . 23 | .Pp 24 | When execline has been configured with the 25 | .Ql --enable-pedantic-posix 26 | option, the 27 | .Pa umask 28 | symbolic link points to the 29 | .Xr posix-umask 1 30 | binary instead. 31 | .Pp 32 | Existing execline scripts calling 33 | .Ql umask 34 | will keep working no matter the chosen configuration. 35 | .Sh SEE ALSO 36 | .Xr emptyenv 1 , 37 | .Xr envfile 1 , 38 | .Xr exec 1 , 39 | .Xr execline-cd 1 , 40 | .Xr exit 1 , 41 | .Xr export 1 , 42 | .Xr fdblock 1 , 43 | .Xr fdclose 1 , 44 | .Xr fdmove 1 , 45 | .Xr fdreserve 1 , 46 | .Xr fdswap 1 , 47 | .Xr getcwd 1 , 48 | .Xr getpid 1 , 49 | .Xr heredoc 1 , 50 | .Xr piperw 1 , 51 | .Xr posix-cd 1 , 52 | .Xr posix-umask 1 , 53 | .Xr redirfd 1 , 54 | .Xr trap 1 , 55 | .Xr tryexec 1 , 56 | .Xr unexport 1 , 57 | .Xr wait 1 , 58 | .Xr withstdinas 1 , 59 | .Xr exec 3 60 | .Pp 61 | This man page is ported from the authoritative documentation at: 62 | .Lk https://skarnet.org/software/execline/execline-umask.html 63 | .Sh AUTHORS 64 | .An Laurent Bercot 65 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 66 | -------------------------------------------------------------------------------- /man1/heredoc.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2011 2 | .Dt HEREDOC 1 3 | .Os 4 | .Sh NAME 5 | .Nm heredoc 6 | .Nd run a command with a certain string fed to a file descriptor 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl d 10 | .Ar fd 11 | .Ar string 12 | .Ar prog... 13 | .Sh DESCRIPTION 14 | .Nm 15 | .Xr exec 3 Ns 16 | s into 17 | .Ar prog... 18 | with 19 | .Ar string 20 | available on the 21 | .Ar fd 22 | file descriptor. 23 | .Pp 24 | .Ar string 25 | must not contain a null character. 26 | .Pp 27 | .Nm 28 | is meant to be used in place of the shell 29 | .Ql << 30 | construct, which includes 31 | .Em here-documents 32 | into scripts. 33 | .Sh OPTIONS 34 | .Bl -tag -width x 35 | .It Fl d 36 | Run the process feeding 37 | .Ar string 38 | to 39 | .Ar fd 40 | as a grandchild of 41 | .Nm . 42 | This is meant to prevent a zombie from hanging around if 43 | .Ar prog... 44 | has read 45 | .Ar string 46 | and fails to wait for its children. 47 | .El 48 | .Sh SEE ALSO 49 | .Xr emptyenv 1 , 50 | .Xr envfile 1 , 51 | .Xr exec 1 , 52 | .Xr execline-cd 1 , 53 | .Xr execline-umask 1 , 54 | .Xr exit 1 , 55 | .Xr export 1 , 56 | .Xr fdblock 1 , 57 | .Xr fdclose 1 , 58 | .Xr fdmove 1 , 59 | .Xr fdreserve 1 , 60 | .Xr fdswap 1 , 61 | .Xr getcwd 1 , 62 | .Xr getpid 1 , 63 | .Xr piperw 1 , 64 | .Xr posix-cd 1 , 65 | .Xr posix-umask 1 , 66 | .Xr redirfd 1 , 67 | .Xr trap 1 , 68 | .Xr tryexec 1 , 69 | .Xr unexport 1 , 70 | .Xr wait 1 , 71 | .Xr withstdinas 1 , 72 | .Xr exec 3 73 | .Pp 74 | This man page is ported from the authoritative documentation at: 75 | .Lk https://skarnet.org/software/execline/heredoc.html 76 | .Sh AUTHORS 77 | .An Laurent Bercot 78 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 79 | -------------------------------------------------------------------------------- /man1/fdblock.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt FDBLOCK 1 3 | .Os 4 | .Sh NAME 5 | .Nm fdblock 6 | .Nd set or unset the 7 | .Dv O_NONBLOCK 8 | flag on a given file descriptor (which makes reading or writing 9 | non-blocking or blocking), then execute a program 10 | .Sh SYNOPSIS 11 | .Nm 12 | .Op Fl n 13 | .Ar fd 14 | .Ar prog... 15 | .Sh DESCRIPTION 16 | .Nm 17 | makes the file descriptor number 18 | .Ar fd 19 | blocking, no matter what its previous state was. 20 | It then execs into 21 | .Ar prog 22 | with its arguments. 23 | .Pp 24 | .Nm 25 | has no portable shell equivalent. 26 | .Sh OPTIONS 27 | .Bl -tag -width x 28 | .It Fl n 29 | Non-blocking. 30 | Sets 31 | .Ar fd 32 | to non-blocking mode instead of blocking mode. 33 | If used on stdin (0) or stdout (1), this option will make a lot of 34 | command-line programs behave improperly, because most simple 35 | command-line programs only support blocking stdin and stdout. 36 | Make sure you know what you are doing. 37 | .El 38 | .Sh SEE ALSO 39 | .Xr emptyenv 1 , 40 | .Xr envfile 1 , 41 | .Xr exec 1 , 42 | .Xr execline-cd 1 , 43 | .Xr execline-umask 1 , 44 | .Xr exit 1 , 45 | .Xr export 1 , 46 | .Xr fdclose 1 , 47 | .Xr fdmove 1 , 48 | .Xr fdreserve 1 , 49 | .Xr fdswap 1 , 50 | .Xr getcwd 1 , 51 | .Xr getpid 1 , 52 | .Xr heredoc 1 , 53 | .Xr piperw 1 , 54 | .Xr posix-cd 1 , 55 | .Xr posix-umask 1 , 56 | .Xr redirfd 1 , 57 | .Xr trap 1 , 58 | .Xr tryexec 1 , 59 | .Xr unexport 1 , 60 | .Xr wait 1 , 61 | .Xr withstdinas 1 62 | .Pp 63 | This man page is ported from the authoritative documentation at: 64 | .Lk https://skarnet.org/software/execline/fdblock.html 65 | .Sh AUTHORS 66 | .An Laurent Bercot 67 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 68 | -------------------------------------------------------------------------------- /man1/execline-cd.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EXECLINE-CD 1 3 | .Os 4 | .Sh NAME 5 | .Nm execline-cd 6 | .Nd change the current working directory to a given directory, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar dir 10 | .Ar prog... 11 | .Sh DESCRIPTION 12 | .Nm 13 | performs a 14 | .Xr chdir 2 15 | system call on 16 | .Ar dir , 17 | then 18 | .Xr exec 3 Ns 19 | s into 20 | .Ar prog... . 21 | .Pp 22 | By default, 23 | .Nm 24 | can also be invoked as 25 | .Ql cd : 26 | there is a 27 | .Pa cd 28 | program which is a symbolic link to 29 | .Nm . 30 | When execline has been configured with the 31 | .Ql --enable-pedantic-posix 32 | option, the 33 | .Pa cd 34 | binary is a symbolic link to the 35 | .Xr posix-cd 1 36 | binary instead, so a 37 | .Ql cd 38 | command in an execline script will invoke 39 | .Xr posix-cd 1 40 | instead of 41 | .Nm 42 | .Pp 43 | Existing scripts that call 44 | .Ql cd 45 | will keep working no matter the chosen configuration. 46 | .Sh SEE ALSO 47 | .Xr emptyenv 1 , 48 | .Xr envfile 1 , 49 | .Xr exec 1 , 50 | .Xr execline-umask 1 , 51 | .Xr exit 1 , 52 | .Xr export 1 , 53 | .Xr fdblock 1 , 54 | .Xr fdclose 1 , 55 | .Xr fdmove 1 , 56 | .Xr fdreserve 1 , 57 | .Xr fdswap 1 , 58 | .Xr getcwd 1 , 59 | .Xr getpid 1 , 60 | .Xr heredoc 1 , 61 | .Xr piperw 1 , 62 | .Xr posix-cd 1 , 63 | .Xr posix-umask 1 , 64 | .Xr redirfd 1 , 65 | .Xr trap 1 , 66 | .Xr tryexec 1 , 67 | .Xr unexport 1 , 68 | .Xr wait 1 , 69 | .Xr withstdinas 1 , 70 | .Xr chdir 2 , 71 | .Xr exec 3 72 | .Pp 73 | This man page is ported from the authoritative documentation at: 74 | .Lk https://skarnet.org/software/execline/execline-cd.html 75 | .Sh AUTHORS 76 | .An Laurent Bercot 77 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 78 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | DESTDIR = 2 | PREFIX = /usr 3 | MAN_DIR ?= $(PREFIX)/share/man 4 | man1_dir = $(MAN_DIR)/man1 5 | man7_dir = $(MAN_DIR)/man7 6 | 7 | man1_targets = \ 8 | background.1 \ 9 | backtick.1 \ 10 | case.1 \ 11 | define.1 \ 12 | dollarat.1 \ 13 | elgetopt.1 \ 14 | elgetpositionals.1 \ 15 | elglob.1 \ 16 | eltest.1 \ 17 | emptyenv.1 \ 18 | envfile.1 \ 19 | exec.1 \ 20 | execline.1 \ 21 | execline-cd.1 \ 22 | execline-shell.1 \ 23 | execline-startup.1 \ 24 | execline-umask.1 \ 25 | execlineb.1 \ 26 | exit.1 \ 27 | export.1 \ 28 | fdblock.1 \ 29 | fdclose.1 \ 30 | fdmove.1 \ 31 | fdreserve.1 \ 32 | fdswap.1 \ 33 | forbacktickx.1 \ 34 | foreground.1 \ 35 | forstdin.1 \ 36 | forx.1 \ 37 | getcwd.1 \ 38 | getpid.1 \ 39 | heredoc.1 \ 40 | homeof.1 \ 41 | if.1 \ 42 | ifelse.1 \ 43 | ifte.1 \ 44 | ifthenelse.1 \ 45 | importas.1 \ 46 | loopwhilex.1 \ 47 | multidefine.1 \ 48 | multisubstitute.1 \ 49 | pipeline.1 \ 50 | piperw.1 \ 51 | posix-cd.1 \ 52 | posix-umask.1 \ 53 | redirfd.1 \ 54 | runblock.1 \ 55 | shift.1 \ 56 | trap.1 \ 57 | tryexec.1 \ 58 | unexport.1 \ 59 | wait.1 \ 60 | withstdinas.1 61 | 62 | man7_targets = \ 63 | execline-block.7 \ 64 | execline-components.7 \ 65 | execline-exitcodes.7 \ 66 | execline-grammar.7 \ 67 | execline-pushenv.7 \ 68 | execline-substitute.7 \ 69 | execline-transform.7 70 | 71 | all: 72 | @echo "Nothing to be done. Ready for 'make install'." 73 | 74 | install: 75 | cd man1; install -D -m 0644 -t ${DESTDIR}${man1_dir} $(man1_targets) 76 | cd man7; install -D -m 0644 -t ${DESTDIR}${man7_dir} $(man7_targets) 77 | 78 | uninstall: 79 | cd $(man1_dir); rm -f $(man1_targets) 80 | cd $(man7_dir); rm -f $(man7_targets) 81 | 82 | .PHONY: all install uninstall 83 | -------------------------------------------------------------------------------- /man1/ifelse.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt IFELSE 1 3 | .Os 4 | .Sh NAME 5 | .Nm ifelse 6 | .Nd perform conditional execution, with two branches 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl X 14 | .Op Fl n 15 | { 16 | .Ar prog1... 17 | } { 18 | .Ar prog2... 19 | } 20 | .Ar prog3... 21 | .Sh DESCRIPTION 22 | .Nm 23 | reads 24 | .Ar prog1... 25 | in a block 26 | .Po 27 | cf.\& 28 | .Xr execline-block 7 29 | .Pc . 30 | It forks and executes it, then waits for it to complete. 31 | .Pp 32 | If 33 | .Ar prog1 34 | crashes, 35 | .Nm 36 | prints an error message and exits 128 plus the number of the signal 37 | that killed 38 | .Ar prog1 . 39 | .Pp 40 | If 41 | .Ar prog1 42 | exits with a return code equal to 0, 43 | .Nm 44 | .Xr exec 3 Ns 45 | s into 46 | .Ar prog2 . 47 | .Pp 48 | Else 49 | .Nm 50 | .Xr exec 3 Ns 51 | s into 52 | .Ar prog3 . 53 | .Pp 54 | .Ql ifelse Ar prog1... No \(dq\(dq Ar prog2... No \(dq\(dq Ar prog3... 55 | is 56 | roughly equivalent to 57 | .Ql sh -c ' Ns Ar prog1... No && exec Ar prog2... No || exec Ar prog3...' . 58 | .Sh OPTIONS 59 | .Bl -tag -width x 60 | .It Fl n 61 | Negate the test. 62 | .It Fl X 63 | Do not die if 64 | .Ar prog1 65 | crashes; treat a crash as a non-zero 66 | .Po 67 | .Dq false 68 | .Pc 69 | exit. 70 | .El 71 | .Sh SEE ALSO 72 | .Xr background 1 , 73 | .Xr backtick 1 , 74 | .Xr execlineb 1 , 75 | .Xr foreground 1 , 76 | .Xr if 1 , 77 | .Xr ifte 1 , 78 | .Xr ifthenelse 1 , 79 | .Xr pipeline 1 , 80 | .Xr runblock 1 , 81 | .Xr exec 3 , 82 | .Xr execline-block 7 83 | .Pp 84 | This man page is ported from the authoritative documentation at: 85 | .Lk https://skarnet.org/software/execline/ifelse.html 86 | .Sh AUTHORS 87 | .An Laurent Bercot 88 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 89 | -------------------------------------------------------------------------------- /man1/getpid.1: -------------------------------------------------------------------------------- 1 | .Dd March 13, 2022 2 | .Dt GETPID 1 3 | .Os 4 | .Sh NAME 5 | .Nm getpid 6 | .Nd store getpid's process ID in a given environment variable, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl E | Fl e 10 | .Op Fl P | Fl p 11 | .Ar var 12 | .Ar prog... 13 | .Sh DESCRIPTION 14 | .Nm 15 | stores its PID in the 16 | .Ar var 17 | variable, then 18 | .Xr exec 3 Ns 19 | s into 20 | .Ar prog 21 | with its arguments. 22 | .Pp 23 | .Ar var 24 | must be given without a dollar! 25 | .Pp 26 | .Ar var 27 | must not contain 28 | .Ql = . 29 | .Sh OPTIONS 30 | .Bl -tag -width x 31 | .It Fl e 32 | No autoimport. 33 | This is the default. 34 | .It Fl E 35 | Autoimport. 36 | Instead of 37 | .Xr exec 3 Ns 38 | ing into 39 | Ar prog... , 40 | .Xr exec 3 41 | into 42 | .Ql importas -ui Ar var Ar var Ar prog... . 43 | This substitutes 44 | .Ar var 45 | into the command line instead of putting it into the environment. 46 | .It Fl p 47 | Get the pid of the current process. 48 | This is the default. 49 | .It Fl P 50 | Use 51 | .Nm Ap s 52 | .Em parent 53 | pid instead. 54 | .El 55 | .Sh SEE ALSO 56 | .Xr emptyenv 1 , 57 | .Xr envfile 1 , 58 | .Xr exec 1 , 59 | .Xr execline-cd 1 , 60 | .Xr execline-umask 1 , 61 | .Xr exit 1 , 62 | .Xr export 1 , 63 | .Xr fdblock 1 , 64 | .Xr fdclose 1 , 65 | .Xr fdmove 1 , 66 | .Xr fdreserve 1 , 67 | .Xr fdswap 1 , 68 | .Xr getcwd 1 , 69 | .Xr heredoc 1 , 70 | .Xr piperw 1 , 71 | .Xr posix-cd 1 , 72 | .Xr posix-umask 1 , 73 | .Xr redirfd 1 , 74 | .Xr trap 1 , 75 | .Xr tryexec 1 , 76 | .Xr unexport 1 , 77 | .Xr wait 1 , 78 | .Xr withstdinas 1 , 79 | .Xr exec 3 80 | .Pp 81 | This man page is ported from the authoritative documentation at: 82 | .Lk https://skarnet.org/software/execline/getpid.html 83 | .Sh AUTHORS 84 | .An Laurent Bercot 85 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 86 | -------------------------------------------------------------------------------- /man1/execline-startup.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EXECLINE-STARTUP 1 3 | .Os 4 | .Sh NAME 5 | .Nm execline-startup 6 | .Nd perform some system-specific login initialization, then execute 7 | .Pa ${HOME}/.execline-loginshell 8 | .Sh SYNOPSIS 9 | .Pa /etc/execline-startup 10 | .Sh DESCRIPTION 11 | .Nm 12 | sets the 13 | .Ev SHELL 14 | environment variable to 15 | .Pa /etc/execline-shell . 16 | It then performs some system-specific initialization, and 17 | transforms itself into 18 | .Ql ${HOME}/.execline-loginshell $@ 19 | if available (and 20 | .Ql /etc/execline-shell 21 | otherwise). 22 | .Pp 23 | .Pa ${HOME}/.execline-loginshell 24 | must be readable and executable by the user. 25 | It must 26 | .Xr exec 3 27 | into 28 | .Ql $SHELL $@ . 29 | .Pp 30 | .Nm 31 | is an 32 | .Xr execlineb 1 33 | script; hence, it is readable and modifiable. 34 | It is meant to be modified by the system administrator to perform 35 | system-specific login-time initialization. 36 | .Pp 37 | As a modifiable configuration file, execline-startup is provided in 38 | execline's 39 | .Pa examples/etc/ 40 | subdirectory, and should be copied by the administrator to 41 | .Pa /etc . 42 | .Pp 43 | .Nm 44 | is meant to be used as a login shell. 45 | System administrators should manually add 46 | .Ql /etc/execline-startup 47 | to the 48 | .Pa /etc/shells 49 | file. 50 | The 51 | .Pa /etc/execline-startup 52 | file itself plays the role of the 53 | .Pa /etc/profile 54 | file, and 55 | .Pa ${HOME}/.execline-loginshell 56 | plays the role of the 57 | .Pa ${HOME}/.profile 58 | file. 59 | .Sh SEE ALSO 60 | .Xr execlineb 1 , 61 | .Xr exec 3 62 | .Pp 63 | This man page is ported from the authoritative documentation at: 64 | .Lk https://skarnet.org/software/execline/execline-startup.html 65 | .Sh AUTHORS 66 | .An Laurent Bercot 67 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 68 | -------------------------------------------------------------------------------- /man1/ifthenelse.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt IFTHENELSE 1 3 | .Os 4 | .Sh NAME 5 | .Nm ifthenelse 6 | .Nd perform a conditional alternative 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl X 14 | .Op Fl s 15 | { 16 | .Ar progif... 17 | } { 18 | .Ar progthen... 19 | } { 20 | .Ar progelse... 21 | } 22 | .Ar prog... 23 | .Sh DESCRIPTION 24 | .Nm 25 | reads 26 | .Ar progif... , 27 | .Ar progthen... 28 | and 29 | .Ar progelse... 30 | in 3 consecutive blocks 31 | .Po 32 | cf.\& 33 | .Xr execline-block 7 34 | .Pc . 35 | .Pp 36 | .Nm 37 | runs 38 | .Ar progif... 39 | as a child process and waits for it to complete. 40 | .Pp 41 | If 42 | .Ar progif... 43 | crashes (i.e. is killed by a signal), 44 | .Nm 45 | prints an error message, then exits 128 plus the number of the signal 46 | that killed 47 | .Ar progif . 48 | .Pp 49 | If 50 | .Ar progif... 51 | exits zero, 52 | .Nm 53 | runs 54 | .Ar progthen... 55 | as a child process, else it runs 56 | .Ar progelse... . 57 | .Pp 58 | .Nm 59 | waits for its child to complete and puts the exit status in the 60 | .Ev \&? 61 | environment variable. 62 | It then 63 | .Xr exec 3 Ns 64 | s into 65 | .Ar prog... . 66 | .Sh OPTIONS 67 | .Bl -tag -width x 68 | .It Fl X 69 | If 70 | .Ar progif 71 | crashes, do not exit; proceed as if it had returned false. 72 | .It Fl s 73 | Magic scoping hack. 74 | This option does powerful but ugly things, and is left undocumented on 75 | purpose. 76 | .El 77 | .Sh SEE ALSO 78 | .Xr background 1 , 79 | .Xr backtick 1 , 80 | .Xr foreground 1 , 81 | .Xr if 1 , 82 | .Xr ifelse 1 , 83 | .Xr ifte 1 , 84 | .Xr pipeline 1 , 85 | .Xr runblock 1 86 | .Pp 87 | This man page is ported from the authoritative documentation at: 88 | .Lk https://skarnet.org/software/execline/ifthenelse.html 89 | .Sh AUTHORS 90 | .An Laurent Bercot 91 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 92 | -------------------------------------------------------------------------------- /man1/exec.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EXEC 1 3 | .Os 4 | .Sh NAME 5 | .Nm exec 6 | .Nd execute the command line it is given 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl c 10 | .Op Fl l 11 | .Op Fl a Ar argv0 12 | .Ar prog... 13 | .Sh DESCRIPTION 14 | .Nm 15 | .Xr exec 3 Ns 16 | s into 17 | .Ar prog... . 18 | It does nothing else. 19 | .Pp 20 | Without options, 21 | .Nm 22 | can be seen as the execline NOP. 23 | .Sh OPTIONS 24 | .Bl -tag -width x 25 | .It Fl c 26 | Empty the environment. 27 | .Ar prog 28 | is executed with no environment variables. 29 | .Sy Warning : 30 | .Ar prog 31 | will run with an empty 32 | .Ev PATH , 33 | so make sure it does not rely on it. 34 | .It Fl l 35 | Login. 36 | Prepends 37 | .Ar prog Ap Ns 38 | s argv[0] with a dash. 39 | .It Fl a Ar argv0 40 | argv0. 41 | Replace 42 | .Ar prog Ap Ns 43 | s argv[0] with 44 | .Ar argv0 . 45 | This is done 46 | .Em before 47 | adding a dash, if the 48 | .Fl l 49 | option is also present. 50 | .El 51 | .Pp 52 | The 53 | .Nm exec 54 | command, along with its options, is designed to emulate the standard 55 | .Ql exec 56 | shell builtin, which replaces the shell with the command it is given. 57 | .Sh SEE ALSO 58 | .Xr emptyenv 1 , 59 | .Xr envfile 1 , 60 | .Xr execline-cd 1 , 61 | .Xr execline-umask 1 , 62 | .Xr exit 1 , 63 | .Xr export 1 , 64 | .Xr fdblock 1 , 65 | .Xr fdclose 1 , 66 | .Xr fdmove 1 , 67 | .Xr fdreserve 1 , 68 | .Xr fdswap 1 , 69 | .Xr getcwd 1 , 70 | .Xr getpid 1 , 71 | .Xr heredoc 1 , 72 | .Xr piperw 1 , 73 | .Xr posix-cd 1 , 74 | .Xr posix-umask 1 , 75 | .Xr redirfd 1 , 76 | .Xr trap 1 , 77 | .Xr tryexec 1 , 78 | .Xr unexport 1 , 79 | .Xr wait 1 , 80 | .Xr withstdinas 1 , 81 | .Xr exec 3 82 | .Pp 83 | This man page is ported from the authoritative documentation at: 84 | .Lk https://skarnet.org/software/execline/exec.html 85 | .Sh AUTHORS 86 | .An Laurent Bercot 87 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 88 | -------------------------------------------------------------------------------- /man1/getcwd.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt GETCWD 1 3 | .Os 4 | .Sh NAME 5 | .Nm getcwd 6 | .Nd store current working directory into a given environment variable, then executes a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl E | Fl e 10 | .Ar var 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | stores a fully resolved absolute path (i.e. without any 15 | .Pa .. 16 | or symbolic link components) to its current working directory into the 17 | .Ar var 18 | variable, then 19 | .Xr exec 3 Ns 20 | s into 21 | .Ar prog 22 | with its arguments. 23 | .Pp 24 | .Ar var 25 | must be given without a dollar! 26 | .Pp 27 | .Ar var 28 | must not contain 29 | .Ql = . 30 | .Pp 31 | Unlike the 32 | .Xr pwd 1 33 | POSIX command, 34 | .Nm 35 | does not depend on the 36 | .Ev PWD 37 | environment variable and will exhibit a consistent behaviour no matter 38 | the environment. 39 | .Sh OPTIONS 40 | .Bl -tag -width x 41 | .It Fl e 42 | No autoimport. 43 | This is the default. 44 | .It Fl E 45 | Autoimport. 46 | Instead of 47 | .Xr exec 3 Ns 48 | ing into 49 | .Ar prog... , 50 | .Xr exec 3 51 | into 52 | .Ql importas -ui Ar var Ar var Ar prog... . 53 | This substitutes 54 | .Ar var 55 | into the command line instead of putting it into the environment. 56 | .El 57 | .Sh SEE ALSO 58 | .Xr emptyenv 1 , 59 | .Xr envfile 1 , 60 | .Xr exec 1 , 61 | .Xr execline-cd 1 , 62 | .Xr execline-umask 1 , 63 | .Xr exit 1 , 64 | .Xr export 1 , 65 | .Xr fdblock 1 , 66 | .Xr fdclose 1 , 67 | .Xr fdmove 1 , 68 | .Xr fdreserve 1 , 69 | .Xr fdswap 1 , 70 | .Xr getpid 1 , 71 | .Xr heredoc 1 , 72 | .Xr piperw 1 , 73 | .Xr posix-cd 1 , 74 | .Xr posix-umask 1 , 75 | .Xr pwd 1 , 76 | .Xr redirfd 1 , 77 | .Xr trap 1 , 78 | .Xr tryexec 1 , 79 | .Xr unexport 1 , 80 | .Xr wait 1 , 81 | .Xr withstdinas 1 , 82 | .Xr exec 3 83 | .Pp 84 | This man page is ported from the authoritative documentation at: 85 | .Lk https://skarnet.org/software/execline/getcwd.html 86 | .Sh AUTHORS 87 | .An Laurent Bercot 88 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 89 | -------------------------------------------------------------------------------- /man1/loopwhilex.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt LOOPWHILEX 1 3 | .Os 4 | .Sh NAME 5 | .Nm loopwhilex 6 | .Nd perform a conditional loop 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl n 10 | .Op Fl o Ar okcodes | Fl x Ar breakcodes 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | runs 15 | .Ar prog... 16 | as a child process and waits for it to complete. 17 | .Pp 18 | As long as 19 | .Ar prog 20 | exits zero, 21 | .Nm 22 | runs it again. 23 | .Pp 24 | .Nm 25 | then exits with an approximation 26 | .Po 27 | cf.\& 28 | .Xr execline-exitcodes 7 29 | .Pc 30 | of the last 31 | .Ar prog 32 | invocation's exit code. 33 | .Pp 34 | .Ql loopwhilex Ar prog... 35 | is equivalent to 36 | .Ql loopwhilex Fl n Fl x No 0 Ar prog... 37 | and 38 | .Ql loopwhilex Fl o No 0 Ar prog... 39 | .Pp 40 | Be careful: execline 41 | .Sy maintains no state , 42 | in particular it uses 43 | .Sy no real variables , 44 | and environment will be of no use here since every instance of 45 | .Ar prog... 46 | runs as a separate child process. 47 | To avoid being stuck in an infinite loop, 48 | .Ar prog... 49 | should modify some external state - for instance, the filesystem. 50 | .Sh OPTIONS 51 | .Bl -tag -width x 52 | .It Fl o Ar okcodes 53 | .Ar okcodes 54 | must be a comma-separated list of exit codes. 55 | .Nm 56 | will keep looping as long as 57 | .Ar prog 58 | exits with one of the codes in 59 | .Ar okcodes . 60 | .It Fl x Ar breakcodes 61 | Like the previous option, but with inverted meaning - the listed exit 62 | codes are codes that will break the loop and exit, and the unlisted 63 | exit codes will keep the loop running. 64 | .It Fl n 65 | Negate the test. 66 | This option is now redundant, and may disappear soon. 67 | .El 68 | .Sh SEE ALSO 69 | .Xr forbacktickx 1 , 70 | .Xr forstdin 1 , 71 | .Xr forx 1 , 72 | .Xr execline-exitcodes 7 73 | .Pp 74 | This man page is ported from the authoritative documentation at: 75 | .Lk https://skarnet.org/software/execline/loopwhilex.html 76 | .Sh AUTHORS 77 | .An Laurent Bercot 78 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 79 | -------------------------------------------------------------------------------- /man1/ifte.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt IFTE 1 3 | .Os 4 | .Sh NAME 5 | .Nm ifte 6 | .Nd perform a conditional alternative 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl X 14 | .Op Fl n 15 | { 16 | .Ar progthen... 17 | } { 18 | .Ar progelse... 19 | } 20 | .Ar progif... 21 | .Sh DESCRIPTION 22 | .Nm 23 | reads 24 | .Ar progthen... 25 | and 26 | .Ar progelse... 27 | in two consecutive blocks 28 | .Po 29 | cf.\& 30 | .Xr execline-block 7 31 | .Pc . 32 | .Pp 33 | .Nm 34 | runs 35 | .Ar progif... 36 | as a child process and waits for it to complete. 37 | .Pp 38 | If 39 | .Ar progif... 40 | crashes (i.e. is killed by a signal), 41 | .Nm 42 | prints an error message, then exits 128 plus the number of the signal 43 | that killed 44 | .Ar progif . 45 | .Pp 46 | If 47 | .Ar progif... 48 | exits zero, 49 | .Nm 50 | .Xr exec 3 Ns 51 | s into 52 | .Ar progthen... , 53 | else it 54 | .Xr exec 3 Ns 55 | s into 56 | .Ar progelse... . 57 | .Pp 58 | .Nm 59 | is a simpler version of 60 | .Xr ifthenelse 1 . 61 | It performs 62 | .Em only 63 | conditional execution, not instruction sequence. 64 | .Pp 65 | .Ql ifthenelse { Ar progif No } { Ar progthen No } { Ar progelse No } remainder 66 | is the equivalent of 67 | .Ql foreground { ifte { Ar progthen No } { Ar progelse No } Ar progif No } remainder . 68 | .Sh OPTIONS 69 | .Bl -tag -width x 70 | .It Fl X 71 | Do not exit if 72 | .Ar progif 73 | crashes; instead, proceed as if the test had returned false. 74 | .It Fl n 75 | Negate the test. 76 | .Ar progthen... 77 | will be run iff 78 | .Ar progif... 79 | exits nonzero. 80 | .El 81 | .Sh SEE ALSO 82 | .Xr background 1 , 83 | .Xr backtick 1 , 84 | .Xr execlineb 1 , 85 | .Xr foreground 1 , 86 | .Xr if 1 , 87 | .Xr ifelse 1 , 88 | .Xr ifthenelse 1 , 89 | .Xr pipeline 1 , 90 | .Xr runblock 1 , 91 | .Xr exec 3 , 92 | .Xr execline-block 7 93 | .Pp 94 | This man page is ported from the authoritative documentation at: 95 | .Lk https://skarnet.org/software/execline/ifte.html 96 | .Sh AUTHORS 97 | .An Laurent Bercot 98 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 99 | -------------------------------------------------------------------------------- /man1/foreground.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt FOREGROUND 1 3 | .Os 4 | .Sh NAME 5 | .Nm foreground 6 | .Nd execute a sequence of commands 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | { 14 | .Ar prog1... 15 | } 16 | .Ar prog2... 17 | .Sh DESCRIPTION 18 | .Nm 19 | reads 20 | .Ar prog1 21 | in a block 22 | .Po 23 | cf.\& 24 | .Xr execline-block 7 25 | .Pc . 26 | It forks and executes it, then waits for it to complete. 27 | .Pp 28 | .Nm 29 | sets the 30 | .Ev \&? 31 | environment variable to the exit code of 32 | .Ar prog1 . 33 | If 34 | .Ar prog1... 35 | was killed by a signal, the 36 | .Ev \&? 37 | value is 256 plus the signal number. 38 | .Pp 39 | .Nm 40 | then 41 | .Xr exec 3 Ns 42 | s into 43 | .Ar prog2... . 44 | .Pp 45 | .Nm 46 | is the basic sequence operator: it takes two commands and executes 47 | them one by one. 48 | execline scripts require it to wrap external commands that exit 49 | instead of natively supporting the 50 | .Dq perform some action, then execute some other program 51 | model. 52 | .Pp 53 | .Ql foreground Ar prog1... \(dq\(dq Ar prog2... 54 | is equivalent to 55 | .Ql sh -c 'Ar prog1... ; exec Ar prog2...' . 56 | .Pp 57 | 256 and above are not valid exit codes for commands, so when the 58 | .Ev \&? 59 | environment variable contains 256 or more, it means that the previous 60 | command was killed by a signal. 61 | There is no ambiguity here, and 62 | .Ev \&? 63 | reports exactly what happened to the previous command; 64 | .Nm 65 | does not exit, so there is no need for exit code approximation 66 | .Po 67 | cf.\& 68 | .Xr execline-exitcodes 7 69 | .Pc . 70 | .Sh SEE ALSO 71 | .Xr background 1 , 72 | .Xr backtick 1 , 73 | .Xr execlineb 1 , 74 | .Xr if 1 , 75 | .Xr ifelse 1 , 76 | .Xr ifte 1 , 77 | .Xr ifthenelse 1 , 78 | .Xr pipeline 1 , 79 | .Xr runblock 1 , 80 | .Xr exec 3 , 81 | .Xr execline-block 7 , 82 | .Xr execline-exitcodes 7 83 | .Pp 84 | This man page is ported from the authoritative documentation at: 85 | .Lk https://skarnet.org/software/execline/foreground.html 86 | .Sh AUTHORS 87 | .An Laurent Bercot 88 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 89 | -------------------------------------------------------------------------------- /man1/pipeline.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt PIPELINE 1 3 | .Os 4 | .Sh NAME 5 | .Nm pipeline 6 | .Nd run two commands with a pipe between them 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl d 14 | .Op Fl r | Fl w 15 | { 16 | .Ar prog1... 17 | } 18 | .Ar prog2... 19 | .Sh DESCRIPTION 20 | .Nm 21 | reads 22 | .Ar prog1... 23 | in a block 24 | .Po 25 | cf.\& 26 | .Xr execline-block 7 27 | .Pc 28 | and unquotes it. 29 | .Pp 30 | It runs 31 | .Ar prog1... 32 | as a child process and 33 | .Xr exec 3 Ns 34 | s into 35 | .Ar prog2... , 36 | with a pipe between 37 | .Ar prog1 Ap 38 | s stdout and 39 | .Ar prog2 Ap 40 | s stdin. 41 | .Pp 42 | .Ar prog1 Ap 43 | s pid is available in 44 | .Ar prog2 45 | as the 46 | .Ev \&! 47 | environment variable. 48 | .Pp 49 | You can easily create a chain of pipes: 50 | .Ql execlineb -Pc 'pipeline { a } pipeline { b } c' 51 | is roughly equivalent to 52 | .Ql sh -c 'exec a | b | c' , 53 | except that shells usually run 54 | .Ql c 55 | as a child process like 56 | .Ql a 57 | and 58 | .Ql b , 59 | and 60 | .Ql exec 61 | has no effect. 62 | .Sh OPTIONS 63 | .Bl -tag -width x 64 | .It Fl d 65 | Run 66 | .Ar prog1... 67 | as a grandchild of 68 | .Nm . 69 | This is meant to prevent a zombie from hanging around if 70 | .Ar prog2... 71 | fails to wait for its children. 72 | .It Fl r 73 | Make 74 | .Ar prog1... 75 | the writer and 76 | .Ar prog2... 77 | the reader. 78 | This is the default. 79 | .It Fl w 80 | Make 81 | .Ar prog1... 82 | the reader and 83 | .Ar prog2... 84 | the writer. 85 | .El 86 | .Sh SEE ALSO 87 | .Xr background 1 , 88 | .Xr backtick 1 , 89 | .Xr execlineb 1 , 90 | .Xr foreground 1 , 91 | .Xr if 1 , 92 | .Xr ifelse 1 , 93 | .Xr ifte 1 , 94 | .Xr ifthenelse 1 , 95 | .Xr runblock 1 , 96 | .Xr exec 3 , 97 | .Xr execline-block 7 98 | .Pp 99 | This man page is ported from the authoritative documentation at: 100 | .Lk https://skarnet.org/software/execline/pipeline.html 101 | .Sh AUTHORS 102 | .An Laurent Bercot 103 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 104 | -------------------------------------------------------------------------------- /man1/fdmove.1: -------------------------------------------------------------------------------- 1 | .Dd February 16, 2021 2 | .Dt FDMOVE 1 3 | .Os 4 | .Sh NAME 5 | .Nm fdmove 6 | .Nd move or copy a given file descriptor, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl c 10 | .Ar fdto 11 | .Ar fdfrom 12 | .Ar prog... 13 | .Sh DESCRIPTION 14 | .Nm 15 | moves the file descriptor number 16 | .Ar fdfrom , 17 | to number 18 | .Ar fdto , 19 | then 20 | .Xr exec 3 Ns s 21 | into 22 | .Ar prog 23 | with its arguments. 24 | If 25 | .Ar fdto 26 | is open, 27 | .Nm 28 | closes it before moving 29 | .Ar fdfrom 30 | to it. 31 | .Pp 32 | .Ql fdmove Ar a Ar b Ar prog... 33 | is roughly equivalent to 34 | .Ql sh -c 'exec Ar prog... Ar a Ns >& Ns Ar b Ar b Ns <&-' . 35 | It means: if you write to fd 36 | .Ar a 37 | now, it will have the same effect as writing to fd 38 | .Ar b 39 | beforehand, and you cannot write to fd 40 | .Ar b 41 | anymore. 42 | .Pp 43 | .Ql fdmove -c Ar a Ar b Ar prog... 44 | is roughly equivalent to 45 | .Ql sh -c 'exec Ar prog... Ar a Ns >& Ns Ar b Ns ' . 46 | It means: you can now write to fd 47 | .Ar a , 48 | and also still write to fd 49 | .Ar b , 50 | and both will have the same effect as writing to fd 51 | .Ar b 52 | beforehand. 53 | .Pp 54 | It also works with file descriptors that are open for reading! 55 | .Sh OPTIONS 56 | .Bl -tag -width x 57 | .It Fl c 58 | Duplicate 59 | .Ar fdfrom 60 | to 61 | .Ar fdto 62 | instead of moving it; do not close 63 | .Ar fdfrom . 64 | .El 65 | .Sh SEE ALSO 66 | .Xr emptyenv 1 , 67 | .Xr envfile 1 , 68 | .Xr exec 1 , 69 | .Xr execline-cd 1 , 70 | .Xr execline-umask 1 , 71 | .Xr exit 1 , 72 | .Xr export 1 , 73 | .Xr fdblock 1 , 74 | .Xr fdclose 1 , 75 | .Xr fdreserve 1 , 76 | .Xr fdswap 1 , 77 | .Xr getcwd 1 , 78 | .Xr getpid 1 , 79 | .Xr heredoc 1 , 80 | .Xr piperw 1 , 81 | .Xr posix-cd 1 , 82 | .Xr posix-umask 1 , 83 | .Xr redirfd 1 , 84 | .Xr trap 1 , 85 | .Xr tryexec 1 , 86 | .Xr unexport 1 , 87 | .Xr wait 1 , 88 | .Xr withstdinas 1 , 89 | .Xr exec 3 90 | .Pp 91 | This man page is ported from the authoritative documentation at: 92 | .Lk https://skarnet.org/software/execline/fdmove.html 93 | .Sh AUTHORS 94 | .An Laurent Bercot 95 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 96 | -------------------------------------------------------------------------------- /man1/tryexec.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt TRYEXEC 1 3 | .Os 4 | .Sh NAME 5 | .Nm tryexec 6 | .Nd execute into a command line, with a fallback 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl n 14 | .Op Fl c 15 | .Op Fl l 16 | .Op Fl a Ar argv0 17 | { 18 | .Ar prog1... 19 | } 20 | .Ar prog2... 21 | .Sh DESCRIPTION 22 | .Nm 23 | reads 24 | .Ar prog1... 25 | in a block 26 | .Po 27 | cf.\& 28 | .Xr execline-block 7 29 | .Pc . 30 | It then executes into it, completely forgetting 31 | .Ar prog2... . 32 | .Pp 33 | If for some reason the 34 | .Xr execve 2 35 | fails - for instance, a non-executable 36 | .Ar prog1 - 37 | then 38 | .Nm 39 | executes into 40 | .Ar prog2... 41 | instead. 42 | .Pp 43 | .Ql tryexec Ar prog1... No \(dq\(dq Ar prog2... 44 | would be equivalent to 45 | .Ql sh -c 'exec Ar prog1... No || exec Ar prog2... Ns ' , 46 | if such a shell construct existed. 47 | Unfortunately, the shell language does not offer that functionality. 48 | .Sh OPTIONS 49 | .Bl -tag -width x 50 | .It Fl n 51 | Reverse 52 | .Ar prog1... 53 | and 54 | .Ar prog2... Ap 55 | s role. 56 | The latter becomes the main execution path and the former becomes the 57 | fallback. 58 | .El 59 | .Pp 60 | The 61 | .Fl c , 62 | .Fl l 63 | and 64 | .Fl a 65 | options have the same semantics as with the 66 | .Xr exec 1 67 | program. 68 | .Sh SEE ALSO 69 | .Xr emptyenv 1 , 70 | .Xr envfile 1 , 71 | .Xr exec 1 , 72 | .Xr execline-cd 1 , 73 | .Xr execline-umask 1 , 74 | .Xr execlineb 1 , 75 | .Xr exit 1 , 76 | .Xr export 1 , 77 | .Xr fdblock 1 , 78 | .Xr fdclose 1 , 79 | .Xr fdmove 1 , 80 | .Xr fdreserve 1 , 81 | .Xr fdswap 1 , 82 | .Xr getcwd 1 , 83 | .Xr getpid 1 , 84 | .Xr heredoc 1 , 85 | .Xr piperw 1 , 86 | .Xr posix-cd 1 , 87 | .Xr posix-umask 1 , 88 | .Xr redirfd 1 , 89 | .Xr trap 1 , 90 | .Xr unexport 1 , 91 | .Xr wait 1 , 92 | .Xr withstdinas 1 , 93 | .Xr execve 2 , 94 | .Xr execline-block 7 95 | .Pp 96 | This man page is ported from the authoritative documentation at: 97 | .Lk https://skarnet.org/software/execline/tryexec.html 98 | .Sh AUTHORS 99 | .An Laurent Bercot 100 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 101 | -------------------------------------------------------------------------------- /man1/elgetopt.1: -------------------------------------------------------------------------------- 1 | .Dd April 3, 2023 2 | .Dt ELGETOPT 1 3 | .Os 4 | .Sh NAME 5 | .Nm elgetopt 6 | .Nd perform 7 | .Xr getopt 1 Ns 8 | -style parsing on the arguments to an execline script 9 | .Sh SYNOPSIS 10 | .Nm 11 | .Op Fl D Ar default 12 | .Ar optstring 13 | .Ar prog... 14 | .Sh DESCRIPTION 15 | .Nm 16 | expects to find a valid number 17 | .Ar n 18 | of arguments in the 19 | .Ev \&# 20 | environment variable, and 21 | .Ar n Ns 22 | +1 environment variables 23 | .Ev 0 , 24 | .Ev 1 , 25 | \&..., 26 | .Ar n . 27 | It exits 100 if it is not the case. 28 | .Pp 29 | .Nm 30 | pushes environment variables 31 | .Po 32 | cf. 33 | .Xr execline-pushenv 7 34 | .Pc 35 | starting with 36 | .Ev ELGETOPT_ . 37 | To get the previous values back, use 38 | .Ql emptyenv -o . 39 | .Pp 40 | .Nm 41 | looks into 42 | .Ev 1 , 43 | .Ev 2 , 44 | \&... for options, as specified by 45 | .Ar optstring , 46 | which is a standard 47 | .Xr getopt 1 48 | string. 49 | .Pp 50 | If the 51 | .Fl c 52 | switch is recognized, 53 | .Nm 54 | sets the 55 | .Ev ELGETOPT_ Ns Ar c 56 | environment variable. 57 | The value of that variable is the argument to the 58 | .Fl c 59 | switch if it has one, and 60 | .Ql 1 61 | .Po 62 | or 63 | .Ar default 64 | if given 65 | .Pc 66 | otherwise. 67 | .Pp 68 | After setting all recognized options, 69 | .Nm 70 | makes new 71 | .Ev \&# , 72 | .Ev 1 , 73 | .Ev 2 , 74 | \&... 75 | .Dq positional parameters 76 | with what remains. 77 | .Pp 78 | .Nm 79 | then execs into 80 | .Ar prog... . 81 | .Pp 82 | GNU-style options are not supported. 83 | .Sh OPTIONS 84 | .Bl -tag -width x 85 | .It Fl D Ar default 86 | Use 87 | .Ar default 88 | as the value for the 89 | .Ev ELGETOPT_ Ns Ar c 90 | environment variable if there is no argument to the 91 | .Fl c 92 | switch. 93 | Default is 94 | .Ql 1 . 95 | The value is the same for all the options defined by 96 | .Nm . 97 | .El 98 | .Sh SEE ALSO 99 | .Xr dollarat 1 , 100 | .Xr getopt 1 , 101 | .Xr shift 1 , 102 | .Xr execline-pushenv 7 103 | .Pp 104 | This man page is ported from the authoritative documentation at: 105 | .Lk https://skarnet.org/software/execline/elgetopt.html 106 | .Sh AUTHORS 107 | .An Laurent Bercot 108 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 109 | -------------------------------------------------------------------------------- /man7/execline-components.7: -------------------------------------------------------------------------------- 1 | .Dd September 28, 2021 2 | .Dt EXECLINE-COMPONENTS 7 3 | .Os 4 | .Sh NAME 5 | .Nm execline-components 6 | .Nd example components of an 7 | .Xr execlineb 1 8 | script 9 | .Sh DESCRIPTION 10 | .Bd -literal 11 | #!/command/execlineb -P 12 | 13 | # This execlineb script will sleep for 1 second, then print some 14 | # silly things on the standard output. 15 | 16 | 17 | foreground # an unquoted string, evaluated to: foreground 18 | { # A single opening brace, not included in the argv 19 | sleep 1 # Two unquoted strings, evaluated to " sleep" and " 1" 20 | # (without the quotation marks). 21 | } # A single closing brace, evaluated to the empty word 22 | 23 | "echo" # this is a quoted string. It will evaluate to the word: echo 24 | 25 | foo\e bar\e zoinx # This is one word, since the spaces are escaped 26 | "foo bar zoinx" # This is exactly the same word, written another way 27 | 28 | " # this is not a comment, since it is inside a quoted string 29 | # This is not a comment either \e" # nor is this " # but this is one 30 | 31 | "\e0x41\e66\e0103D\en" # This is the string ABCD followed by a newline. 32 | # Be careful: the newline will be part of the word. 33 | 34 | \en # this is not a newline, but the single word: n 35 | 36 | $23 # This will NOT be replaced by anything with execline-1.y, unless 37 | # substitution is explicitly asked for in the script. 38 | # The dollar is no special character for the execline binary. 39 | 40 | baz"\&$1"qux # This will evaluate to the word baz$1qux 41 | baz\e$1qux # Same here 42 | baz$1qux # Same here in execline-1.y 43 | 44 | ${PATH} # This will NOT be replaced by execline ; use the importas command 45 | # if you need the $PATH value. 46 | 47 | \&'this is not a string\&' # it will be parsed as five separate words 48 | 49 | "\e 50 | " # This will be parsed as the empty word. A (backslash, newline) 51 | # sequence inside a quoted string is entirely removed. 52 | .Ed 53 | .Sh SEE ALSO 54 | This man page is ported from the authoritative documentation at: 55 | .Lk https://skarnet.org/software/execline/componentsb.txt 56 | .Sh AUTHORS 57 | .An Laurent Bercot 58 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 59 | -------------------------------------------------------------------------------- /man1/emptyenv.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EMPTYENV 1 3 | .Os 4 | .Sh NAME 5 | .Nm emptyenv 6 | .Nd empty the current environment, or clean it up; then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl p 10 | .Ar prog... 11 | .Nm 12 | .Fl c 13 | .Ar prog... 14 | .Nm 15 | .Op Fl o 16 | .Op Fl P 17 | .Ar prog... 18 | .Sh DESCRIPTION 19 | By default, 20 | .Nm 21 | unsets all environment variables, then 22 | .Xr exec 3 Ns 23 | s into 24 | .Ar prog 25 | with its arguments. 26 | Options control which environment variables are unset. 27 | .Sh OPTIONS 28 | .Bl -tag -width x 29 | .It Fl p 30 | Keep the 31 | .Ev PATH 32 | environment variable. 33 | .It Fl c 34 | Clean up. 35 | Do not empty the environment. 36 | Instead, remove every variable used internally by the execline 37 | programs, to avoid any interference with or information leakage to 38 | external programs. 39 | .It Fl o 40 | Pop 41 | .Po 42 | cf.\& 43 | .Xr execline-pushenv 7 44 | .Pc 45 | environment variables starting with 46 | .Ql ELGETOPT_ . 47 | You might want to do this before executing a final program from a 48 | script that uses 49 | .Xr elgetopt 1 . 50 | .It Fl P 51 | Pop 52 | .Po 53 | cf.\& 54 | .Xr execline-pushenv 7 55 | .Pc 56 | environment variables starting with 57 | .Ql # , 58 | .Ql 0 59 | to 60 | .Ql 9 , 61 | and 62 | .Ql EXECLINE_ . 63 | You might want to do this before executing a final program from a 64 | script launched by 65 | .Xr execlineb 1 . 66 | .El 67 | .Sh SEE ALSO 68 | .Xr elgetopt 1 , 69 | .Xr envfile 1 , 70 | .Xr exec 1 , 71 | .Xr execline-cd 1 , 72 | .Xr execline-umask 1 , 73 | .Xr execlineb 1 , 74 | .Xr exit 1 , 75 | .Xr export 1 , 76 | .Xr fdblock 1 , 77 | .Xr fdclose 1 , 78 | .Xr fdmove 1 , 79 | .Xr fdreserve 1 , 80 | .Xr fdswap 1 , 81 | .Xr getcwd 1 , 82 | .Xr getpid 1 , 83 | .Xr heredoc 1 , 84 | .Xr piperw 1 , 85 | .Xr posix-cd 1 , 86 | .Xr posix-umask 1 , 87 | .Xr redirfd 1 , 88 | .Xr trap 1 , 89 | .Xr tryexec 1 , 90 | .Xr unexport 1 , 91 | .Xr wait 1 , 92 | .Xr withstdinas 1 , 93 | .Xr execline-pushenv 7 94 | .Pp 95 | This man page is ported from the authoritative documentation at: 96 | .Lk https://skarnet.org/software/execline/emptyenv.html 97 | .Sh AUTHORS 98 | .An Laurent Bercot 99 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 100 | -------------------------------------------------------------------------------- /man1/shift.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt SHIFT 1 3 | .Os 4 | .Sh NAME 5 | .Nm shift 6 | .Nd shift the positional parameters of an execline script 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl n Ar argn 10 | .Op Fl b Ar blockn 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | shifts 15 | .Ar argn 16 | positional parameters, then 17 | .Ar blockn 18 | blocks. 19 | It then 20 | .Xr exec 3 Ns 21 | s 22 | .Ar prog... . 23 | .Pp 24 | By default, 25 | .Ar argn 26 | and 27 | .Ar blockn 28 | are both zero; but if neither the 29 | .Fl n 30 | nor the 31 | .Fl b 32 | option is given, then 33 | .Ar argn 34 | is 1 and 35 | .Ar blockn 36 | is 0. 37 | .Pp 38 | .Ql shift 39 | is a standard shell builtin. 40 | Be careful if you want to use it outside of an execline script. 41 | .Pp 42 | The 43 | .Fl b 44 | option is only useful to implement execline commands in the execline 45 | language. 46 | You shouldn't normally have to use it. 47 | .Ss Details 48 | .Bl -bullet -width x 49 | .It 50 | .Nm 51 | reads the number of 52 | .Dq positional parameters 53 | in the 54 | .Ev \&# 55 | environment variable. 56 | Let 57 | .Ar n 58 | be that number. 59 | .It 60 | If the 61 | .Ev \&# 62 | environment variable is not set or does not contain a valid number, or 63 | one of the 64 | .Ev 0 , 65 | .Ev 1 , 66 | \&..., 67 | .Ar n 68 | environment variables is not set, 69 | .Nm 70 | exits 100 with an error message. 71 | .It 72 | .Nm 73 | calculates a shift value 74 | .Ar m , 75 | corresponding to 76 | .Ar argn 77 | arguments followed by enough arguments to make 78 | .Ar blockn 79 | blocks. 80 | .It 81 | It shifts the positional parameters 82 | .Ar m 83 | times: the value of the 84 | .Sm off 85 | .Ar m 86 | +1 87 | .Sm on 88 | variable becomes the value of the 89 | .Ev 1 90 | variable, 91 | .Sm off 92 | .Ar m 93 | +2 94 | .Sm on 95 | becomes 96 | .Ev 2 97 | and so on, and 98 | .Ev \&# 99 | is set to 100 | .Sm off 101 | .Ar n 102 | - 103 | .Ar m 104 | .Sm on 105 | (floored at zero). 106 | .It 107 | .Nm 108 | then 109 | .Xr exec 3 Ns 110 | s into 111 | .Ar prog... . 112 | .El 113 | .Sh SEE ALSO 114 | .Xr dollarat 1 , 115 | .Xr elgetopt 1 , 116 | .Xr exec 3 117 | .Pp 118 | This man page is ported from the authoritative documentation at: 119 | .Lk https://skarnet.org/software/execline/shift.html 120 | .Sh AUTHORS 121 | .An Laurent Bercot 122 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 123 | -------------------------------------------------------------------------------- /man1/elglob.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt ELGLOB 1 3 | .Os 4 | .Sh NAME 5 | .Nm elglob 6 | .Nd perform globbing on a pattern, then execute another program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl v 10 | .Op Fl w 11 | .Op Fl s 12 | .Op Fl m 13 | .Op Fl e 14 | .Op Fl 0 15 | .Ar variable 16 | .Ar pattern 17 | .Ar prog... 18 | .Sh DESCRIPTION 19 | .Nm 20 | performs globbing[1] on 21 | .Ar pattern . 22 | .Pp 23 | It then performs 24 | variable substitution 25 | .Po 26 | cf. 27 | .Xr execline-substitute 7 28 | .Pc 29 | on 30 | .Ar prog... , 31 | using 32 | .Ar variable 33 | as key and the result of the globbing as value. 34 | The value is always split: it contains as many words as they are 35 | matches for the globbing pattern. 36 | .Pp 37 | .Nm 38 | then 39 | .Xr exec 3 Ns 40 | s into the modified 41 | .Ar prog... . 42 | .Sh OPTIONS 43 | .Bl -tag -width x 44 | .It Fl v 45 | Verbose. 46 | If there is a problem while globbing, print a warning message on 47 | stderr. 48 | .It Fl w 49 | Strict. 50 | If there is a problem while globbing, die immediately. 51 | This is harsh - you probably don't need that option. 52 | .It Fl s 53 | Sort the matches. 54 | By default, the results are left unsorted. 55 | .It Fl m 56 | Mark. 57 | Append a slash to each word that corresponds to a directory. 58 | .It Fl e 59 | No escape. 60 | Treat backslashes in 61 | .Ar pattern 62 | literally; do not allow quoting of metacharacters in 63 | .Ar pattern 64 | via backslashes. 65 | .Sy Warning : 66 | the 67 | .Xr execlineb 1 68 | launcher uses the backslash as their own escape character - if you 69 | want a backslash to be passed to 70 | .Nm , 71 | do not forget to 72 | .Em double 73 | it. 74 | .It Fl 0 75 | Null globbing. 76 | By default, if 77 | .Ar pattern 78 | matches nothing, it will be substituted as is (verbatim in one 79 | word). 80 | With this option, if 81 | .Ar pattern 82 | matches nothing, it will be properly substituted as zero word. 83 | .El 84 | .Sh SEE ALSO 85 | .Xr define 1 , 86 | .Xr elgetpositionals 1 , 87 | .Xr execlineb 1 , 88 | .Xr importas 1 , 89 | .Xr multidefine 1 , 90 | .Xr multisubstitute 1 , 91 | .Xr execline-substitute 7 92 | .Pp 93 | [1] 94 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/functions/glob.html 95 | .Pp 96 | This man page is ported from the authoritative documentation at: 97 | .Lk https://skarnet.org/software/execline/elglob.html 98 | .Sh AUTHORS 99 | .An Laurent Bercot 100 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 101 | -------------------------------------------------------------------------------- /man1/if.1: -------------------------------------------------------------------------------- 1 | .Dd February 16, 2021 2 | .Dt IF 1 3 | .Os 4 | .Sh NAME 5 | .Nm if 6 | .Nd perform conditional execution 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl X 14 | .Op Fl n 15 | .Op Fl t | Fl x Ar exitcode 16 | { 17 | .Ar prog1... 18 | } 19 | .Ar prog2... 20 | .Sh DESCRIPTION 21 | .Nm 22 | reads 23 | .Ar prog1... 24 | in a block 25 | .Po 26 | cf.\& 27 | .Xr execline-block 7 28 | .Pc . 29 | It forks and executes it, then waits for it to complete. 30 | .Pp 31 | If 32 | .Ar prog1 33 | crashes, 34 | .Nm 35 | prints an error message then exits 128 plus the number of the signal that killed 36 | .Ar prog1 . 37 | .Pp 38 | If 39 | .Ar prog1 40 | exits with a non-zero code, 41 | .Nm 42 | exits with an approximation 43 | .Po 44 | cf.\& 45 | .Xr execline-exitcodes 7 46 | .Pc 47 | of that code. 48 | .Pp 49 | Else 50 | .Nm 51 | .Xr exec 3 Ns 52 | s into 53 | .Ar prog2 . 54 | .Pp 55 | .Nm 56 | will exit if 57 | .Ar prog1... 58 | exits false. 59 | To use it in an execline script that must run 60 | .Ar prog3... 61 | no matter the result of the test, use a 62 | .Xr foreground 1 63 | wrapper: 64 | .Bd -literal -offset indent 65 | foreground { if { prog1... } prog2... } prog3... 66 | .Ed 67 | .Pp 68 | (in 69 | .Xr execlineb 1 70 | syntax). 71 | .Pp 72 | .Ql if Ar prog1... No \(dq\(dq Ar prog2... 73 | is equivalent to 74 | .Ql sh -c ' Ns Ar prog1... No && exec Ar prog2...' . 75 | .Sh OPTIONS 76 | .Bl -tag -width x 77 | .It Fl X 78 | Treat a crash of 79 | .Ar prog1 80 | as a non-zero 81 | .Po 82 | .Dq false 83 | .Pc 84 | exit. 85 | This is mostly useful in combination with 86 | .Fl n . 87 | .It Fl n 88 | Negate the test. 89 | If 90 | .Ar prog1 91 | exits true, then 92 | .Nm 93 | will exit 1; else it will 94 | .Xr exec 3 95 | into 96 | .Ar prog2 . 97 | .It Fl x Ar exitcode 98 | If 99 | .Nm 100 | needs to exit, it will exit 101 | .Ar exitcode 102 | instead of whatever else it would have exited. 103 | .It Fl t 104 | If 105 | .Nm if 106 | needs to exit, it will exit 0. 107 | This is equivalent to 108 | .Ql -x 0 . 109 | .El 110 | .Sh SEE ALSO 111 | .Xr background 1 , 112 | .Xr backtick 1 , 113 | .Xr execlineb 1 , 114 | .Xr foreground 1 , 115 | .Xr ifelse 1 , 116 | .Xr ifte 1 , 117 | .Xr ifthenelse 1 , 118 | .Xr pipeline 1 , 119 | .Xr runblock 1 , 120 | .Xr exec 3 , 121 | .Xr execline-block 7 122 | .Pp 123 | This man page is ported from the authoritative documentation at: 124 | .Lk https://skarnet.org/software/execline/if.html 125 | .Sh AUTHORS 126 | .An Laurent Bercot 127 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 128 | -------------------------------------------------------------------------------- /man1/posix-cd.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt POSIX-CD 1 3 | .Os 4 | .Sh NAME 5 | .Nm posix-cd 6 | .Nd change the current working directory to a given directory, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl L | Fl P 10 | .Ar dir 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | changes the current working directory to 15 | .Ar dir 16 | according to the POSIX specification for a 17 | .Ql cd 18 | external utility[1]. 19 | Then, if 20 | .Ar prog... 21 | is not empty, it execs into it. 22 | .Pp 23 | When execline has been configured with the 24 | .Ql --enable-pedantic-posix 25 | option, the 26 | .Pa cd 27 | command is a symbolic link to it. 28 | So scripts calling 29 | .Pa cd 30 | will use 31 | .Nm . 32 | When this configuration option has not been given, 33 | .Pa cd 34 | is a symbolic link to 35 | .Xr execline-cd 1 . 36 | .Pp 37 | .Nm 38 | fully conforms to the POSIX specification[1]. 39 | When 40 | .Ar prog... 41 | is not empty, the behaviour of a 42 | .Ql cd 43 | utility is not specified by POSIX, so 44 | .Nm 45 | extends the spec to be actually useful and usable in an execline 46 | program with the same interface as the regular execline 47 | .Ql cd 48 | command 49 | .Po 50 | cf.\& 51 | .Xr execline-cd 1 52 | .Pc . 53 | .Pp 54 | Nobody ever executes or needs the external version (i.e. not a shell 55 | builtin) of the POSIX 56 | .Ql cd 57 | command. 58 | Compared to execline's regular 59 | .Pa cd 60 | binary, 61 | .Xr execline-cd 1 , 62 | .Nm 63 | is uselessly bloated and slow. 64 | The only reason it exists is that some distributions refuse to package 65 | execline correctly unless it is strictly POSIX-compliant; the 66 | .Ql --enable-pedantic-posix 67 | configure option is there to satisfy their requirements. 68 | .Sh SEE ALSO 69 | .Xr emptyenv 1 , 70 | .Xr envfile 1 , 71 | .Xr exec 1 , 72 | .Xr execline-cd 1 , 73 | .Xr execline-umask 1 , 74 | .Xr exit 1 , 75 | .Xr export 1 , 76 | .Xr fdblock 1 , 77 | .Xr fdclose 1 , 78 | .Xr fdmove 1 , 79 | .Xr fdreserve 1 , 80 | .Xr fdswap 1 , 81 | .Xr getcwd 1 , 82 | .Xr getpid 1 , 83 | .Xr heredoc 1 , 84 | .Xr piperw 1 , 85 | .Xr posix-umask 1 , 86 | .Xr redirfd 1 , 87 | .Xr trap 1 , 88 | .Xr tryexec 1 , 89 | .Xr unexport 1 , 90 | .Xr wait 1 , 91 | .Xr withstdinas 1 92 | .Pp 93 | [1] 94 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/utilities/cd.html 95 | .Pp 96 | This man page is ported from the authoritative documentation at: 97 | .Lk https://skarnet.org/software/execline/posix-cd.html 98 | .Sh AUTHORS 99 | .An Laurent Bercot 100 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 101 | -------------------------------------------------------------------------------- /man1/fdreserve.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt FDRESERVE 1 3 | .Os 4 | .Sh NAME 5 | .Nm fdreserve 6 | .Nd update the environment with file descriptors that are guaranteed safe to use, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar n 10 | .Ar prog... 11 | .Sh DESCRIPTION 12 | .Nm 13 | tries to reserve 14 | .Ar n 15 | file descriptors. 16 | .Pp 17 | .Nm 18 | sets the 19 | .Ev FD0 , 20 | .Ev FD1 , 21 | \&..., 22 | .Ev FD Ns Ar n-1 23 | environment variables: each FD 24 | .Ar i 25 | contains a valid file descriptor, that can be safely opened. 26 | .Pp 27 | .Nm 28 | then 29 | .Xr exec 3 Ns 30 | s into 31 | .Ar prog 32 | with its arguments. 33 | .Ss Common use 34 | .Nm 35 | can be used when you do not want to hardcode file descriptors in your 36 | scripts. 37 | For instance, to create a pipe, you could use: 38 | .Bd -literal -offset indent 39 | #!/command/execlineb 40 | fdreserve 2 41 | multisubstitute 42 | { 43 | importas fdr FD0 44 | importas fdw FD1 45 | } 46 | piperw $fdr $fdw 47 | prog... 48 | .Ed 49 | .Pp 50 | Warning: 51 | .Nm 52 | does not allocate descriptors, it merely returns descriptors that are 53 | free at the time it is run. 54 | A program like 55 | .Bd -literal -offset indent 56 | #!/command/execlineb 57 | fdreserve 3 58 | multisubstitute 59 | { 60 | importas fdr FD0 61 | importas fdw FD1 62 | } 63 | piperw $fdr $fdw 64 | fdreserve 1 65 | multisubstitute 66 | { 67 | importas oldfd FD2 68 | importas newfd FD0 69 | } 70 | prog... 71 | .Ed 72 | .Pp 73 | may fail, because 74 | .Ar oldfd 75 | and 76 | .Ar newfd 77 | may be the same. 78 | To avoid that, you should make sure that all descriptors returned by 79 | .Nm 80 | are actually allocated before calling 81 | .Nm 82 | again. 83 | (Thanks to Paul Jarc[1] for having spotted that case.) 84 | .Sh SEE ALSO 85 | .Xr emptyenv 1 , 86 | .Xr envfile 1 , 87 | .Xr exec 1 , 88 | .Xr execline-cd 1 , 89 | .Xr execline-umask 1 , 90 | .Xr exit 1 , 91 | .Xr export 1 , 92 | .Xr fdblock 1 , 93 | .Xr fdclose 1 , 94 | .Xr fdmove 1 , 95 | .Xr fdswap 1 , 96 | .Xr getcwd 1 , 97 | .Xr getpid 1 , 98 | .Xr heredoc 1 , 99 | .Xr piperw 1 , 100 | .Xr posix-cd 1 , 101 | .Xr posix-umask 1 , 102 | .Xr redirfd 1 , 103 | .Xr trap 1 , 104 | .Xr tryexec 1 , 105 | .Xr unexport 1 , 106 | .Xr wait 1 , 107 | .Xr withstdinas 1 , 108 | .Xr exec 3 109 | .Pp 110 | [1] 111 | .Lk https://code.dogmap.org/ 112 | .Pp 113 | This man page is ported from the authoritative documentation at: 114 | .Lk https://skarnet.org/software/execline/fdreserve.html 115 | .Sh AUTHORS 116 | .An Laurent Bercot 117 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 118 | -------------------------------------------------------------------------------- /man1/runblock.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt RUNBLOCK 1 3 | .Os 4 | .Sh NAME 5 | .Nm runblock 6 | .Nd execute an 7 | .Xr execline-block 7 8 | .Sh SYNOPSIS 9 | .Nm 10 | .Op Fl P 11 | .Op Fl n Ar argshift 12 | .Op Fl r 13 | .Ar n 14 | .Ar cmd... 15 | .Sh DESCRIPTION 16 | .Nm Ap 17 | s purpose is to help you write execline commands in the execline language. 18 | It can only be used inside an execline script. 19 | If the script has been given blocks as arguments, 20 | .Nm 21 | allows you to execute one of the blocks individually. 22 | It also allows you to give those blocks as a set of arguments to 23 | another command. 24 | .Pp 25 | .Nm 26 | skips the first 27 | .Ar argshift 28 | positional parameters. 29 | It does that to allow you to design commands that take simple 30 | arguments 31 | .Em and 32 | blocks. 33 | .Pp 34 | Then 35 | .Nm 36 | looks for and parses blocks 37 | .Po 38 | cf.\& 39 | .Xr execline-block 7 40 | .Pc 41 | in the positional parameters. 42 | .Pp 43 | If the 44 | .Fl r 45 | option is present: 46 | .Nm 47 | skips 48 | .Ar n 49 | blocks and execs into the remaining arguments. 50 | .Pp 51 | Else it skips 52 | .Ar n Ns 53 | -1 blocks and execs into the 54 | .Ar n Ns 55 | th one. 56 | .Pp 57 | If 58 | .Ar cmd... 59 | is not empty, then instead of directly executing the block or the remainder, 60 | .Nm 61 | .Em appends 62 | the selected set of arguments to the 63 | .Ar cmd... 64 | command line. 65 | .Pp 66 | Normally 67 | .Nm 68 | pops 69 | .Po 70 | cf.\& 71 | .Xr execline-pushenv 7 72 | .Pc 73 | its environment frame before executing. 74 | If the 75 | .Fl P 76 | option has been given, it 77 | .Em does not 78 | pop. 79 | .Pp 80 | Of course, if the block structure doesn't match, 81 | .Nm 82 | exits 100 with an error message. 83 | .Ss Credits 84 | The 85 | .Nm runblock 86 | idea, as well as the 87 | .Xr ifelse 1 88 | idea, comes from Paul Jarc[1]. 89 | .Sh EXAMPLES 90 | Suppose that we want to implement the 91 | .Xr ifelse 1 92 | command as an execline script, using the 93 | .Xr ifte 1 94 | command. 95 | .Nm 96 | allows us to do it in a simple way: 97 | .Bd -literal -offset indent 98 | #!/command/execlineb 99 | ifte { runblock 2 } { runblock -r 2 } runblock 1 100 | .Ed 101 | .Pp 102 | That's it. 103 | .Sh SEE ALSO 104 | .Xr background 1 , 105 | .Xr backtick 1 , 106 | .Xr foreground 1 , 107 | .Xr if 1 , 108 | .Xr ifelse 1 , 109 | .Xr ifte 1 , 110 | .Xr ifthenelse 1 , 111 | .Xr pipeline 1 112 | .Pp 113 | [1] 114 | .Lk https://code.dogmap.org/ 115 | .Pp 116 | This man page is ported from the authoritative documentation at: 117 | .Lk https://skarnet.org/software/execline/runblock.html 118 | .Sh AUTHORS 119 | .An Laurent Bercot 120 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 121 | -------------------------------------------------------------------------------- /man1/posix-umask.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt POSIX-UMASK 1 3 | .Os 4 | .Sh NAME 5 | .Nm posix-umask 6 | .Nd change file mode creation mask, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl S 10 | .Op Ar mask 11 | .Op Ar prog... 12 | .Sh DESCRIPTION 13 | When called with no argument, 14 | .Nm 15 | prints the value of the file mode creation mask of the invoking 16 | process, then exits 0. 17 | .Pp 18 | When called with a 19 | .Ar mask 20 | argument, 21 | .Nm 22 | changes its file mode creation mask; then, if 23 | .Ar prog... 24 | is not empty, it 25 | .Xr exec 3 Ns 26 | s into it. 27 | .Pp 28 | .Nm 29 | interprets 30 | .Ar mask 31 | as specified by the POSIX specification for a 32 | .Ql umask 33 | external utility[1]. 34 | .Pp 35 | When execline has been configured with the 36 | .Ql --enable-pedantic-posix 37 | option, the 38 | .Pa umask 39 | command is a symbolic link to it. 40 | So scripts calling 41 | .Pa umask 42 | will use 43 | .Nm . 44 | When this configuration option has not been given, 45 | .Pa umask 46 | is a symbolic link to 47 | .Xr execline-umask 1 . 48 | .Pp 49 | .Nm 50 | fully conforms to the POSIX specification[1]. 51 | When 52 | .Ar prog... 53 | is not empty, the behaviour of a 54 | .Ql umask 55 | utility is not specified by POSIX, so 56 | .Nm 57 | extends the spec to be actually useful and usable in an execline 58 | program with the same interface as the regular execline 59 | .Ql umask 60 | command. 61 | .Pp 62 | Nobody ever executes or needs the external version (i.e. not a shell 63 | builtin) of the POSIX 64 | .Ql umask 65 | command. 66 | Compared to execline's regular 67 | .Pa umask 68 | binary, 69 | .Xr execline-umask 1 , 70 | .Nm 71 | is uselessly bloated and slow. 72 | The only reason it exists is that some distributions refuse to package 73 | execline correctly unless it is strictly POSIX-compliant; the 74 | .Ql --enable-pedantic-posix 75 | configure option is there to satisfy their requirements. 76 | .Sh SEE ALSO 77 | .Xr emptyenv 1 , 78 | .Xr envfile 1 , 79 | .Xr exec 1 , 80 | .Xr execline-cd 1 , 81 | .Xr execline-umask 1 , 82 | .Xr exit 1 , 83 | .Xr export 1 , 84 | .Xr fdblock 1 , 85 | .Xr fdclose 1 , 86 | .Xr fdmove 1 , 87 | .Xr fdreserve 1 , 88 | .Xr fdswap 1 , 89 | .Xr getcwd 1 , 90 | .Xr getpid 1 , 91 | .Xr heredoc 1 , 92 | .Xr piperw 1 , 93 | .Xr posix-cd 1 , 94 | .Xr redirfd 1 , 95 | .Xr trap 1 , 96 | .Xr tryexec 1 , 97 | .Xr unexport 1 , 98 | .Xr wait 1 , 99 | .Xr withstdinas 1 100 | .Pp 101 | [1] 102 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/utilities/umask.html 103 | .Pp 104 | This man page is ported from the authoritative documentation at: 105 | .Lk https://skarnet.org/software/execline/posix-umask.html 106 | .Sh AUTHORS 107 | .An Laurent Bercot 108 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 109 | -------------------------------------------------------------------------------- /man1/withstdinas.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt WITHSTDINAS 1 3 | .Os 4 | .Sh NAME 5 | .Nm withstdinas 6 | .Nd read the entirety of standard input in an environment variable, and run another program with that additional environment variable 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl i | Fl I | Fl D Ar default 14 | .Op Fl N | Fl n 15 | .Op Fl E | Fl e 16 | .Ar variable 17 | .Ar prog... 18 | .Sh DESCRIPTION 19 | .Nm 20 | reads its stdin until EOF. 21 | .Pp 22 | It then 23 | .Xr exec 3 Ns 24 | s into 25 | .Ar prog... , 26 | with 27 | .Ar variable 28 | added to the environment; the value of 29 | .Ar variable 30 | is what was read on stdin. 31 | .Pp 32 | You can start 33 | .Ar prog... 34 | with 35 | .Ql importas -u Ar variable Ar variable 36 | to perform variable substitution. 37 | .Sh OPTIONS 38 | .Bl -tag -width x 39 | .It Fl N 40 | Do not chomp an ending newline off stdin. 41 | .It Fl n 42 | Chomp an ending newline off stdin. 43 | This is the default. 44 | .It Fl e 45 | No autoimport. 46 | This is the default. 47 | .It Fl E 48 | Autoimport. 49 | Instead of 50 | .Xr exec 3 Ns 51 | ing into 52 | .Ar prog... , 53 | .Xr exec 3 54 | into 55 | .Ql importas -ui Ar variable Ar variable Ar prog... . 56 | This substitutes 57 | .Ar variable 58 | into the command line instead of putting it into the environment. 59 | .El 60 | .Pp 61 | The other options tell 62 | .Nm 63 | what to do if its input is not suitable as the contents of an 64 | environment variable, i.e. it contains a null character: 65 | .Bl -tag -width x 66 | .It Fl i 67 | .Nm 68 | exits 1. 69 | .It Fl I 70 | .Ar variable 71 | is 72 | .Sy removed 73 | from the environment, and execution proceeds. 74 | .It Fl D Ar default 75 | The value of 76 | .Ar variable 77 | is set to 78 | .Ar default , 79 | and execution proceeds. 80 | .El 81 | .Pp 82 | When neither of those options is given, the value of 83 | .Ar variable 84 | is set to whatever the start of the input is, up to the first null 85 | character; and execution proceeds. 86 | .Sh SEE ALSO 87 | .Xr emptyenv 1 , 88 | .Xr envfile 1 , 89 | .Xr exec 1 , 90 | .Xr execline-cd 1 , 91 | .Xr execline-umask 1 , 92 | .Xr execlineb 1 , 93 | .Xr exit 1 , 94 | .Xr export 1 , 95 | .Xr fdblock 1 , 96 | .Xr fdclose 1 , 97 | .Xr fdmove 1 , 98 | .Xr fdreserve 1 , 99 | .Xr fdswap 1 , 100 | .Xr getcwd 1 , 101 | .Xr getpid 1 , 102 | .Xr heredoc 1 , 103 | .Xr piperw 1 , 104 | .Xr posix-cd 1 , 105 | .Xr posix-umask 1 , 106 | .Xr redirfd 1 , 107 | .Xr trap 1 , 108 | .Xr tryexec 1 , 109 | .Xr unexport 1 , 110 | .Xr wait 1 , 111 | .Xr exec 3 112 | .Pp 113 | This man page is ported from the authoritative documentation at: 114 | .Lk https://skarnet.org/software/execline/withstdinas.html 115 | .Sh AUTHORS 116 | .An Laurent Bercot 117 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 118 | -------------------------------------------------------------------------------- /man1/importas.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt IMPORTAS 1 3 | .Os 4 | .Sh NAME 5 | .Nm importas 6 | .Nd replace a literal with the value of an environment variable, then execute another program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl i | Fl D Ar default 10 | .Op Fl u 11 | .Op Fl s 12 | .Op Fl C | Fl c 13 | .Op Fl N | Fl n 14 | .Op Fl d Ar delim 15 | .Ar variable 16 | .Ar envvar 17 | .Ar prog... 18 | .Sh DESCRIPTION 19 | .Nm 20 | fetches the value of 21 | .Ar envvar 22 | in the environment. 23 | If neither the 24 | .Fl D 25 | nor the 26 | .Fl i 27 | option is given, and 28 | .Ar envvar 29 | is undefined, 30 | .Sy no word 31 | is returned (that is different from the empty word). 32 | .Pp 33 | .Nm 34 | then performs variable substitution 35 | .Po 36 | cf.\& 37 | .Xr execline-substitute 7 38 | .Pc 39 | on 40 | .Ar prog... , 41 | with 42 | .Ar variable 43 | as key and that string as value. 44 | .Pp 45 | .Nm 46 | then 47 | .Xr exec 3 Ns 48 | s into the modified 49 | .Ar prog... . 50 | .Pp 51 | When 52 | .Ar envvar 53 | is undefined, and the 54 | .Fl D 55 | option is not given, any variable substitution 56 | .Po 57 | cf.\& 58 | .Xr execline-substitute 7 59 | .Pc 60 | with 61 | .Ar variable 62 | as the key will return no word; that is true even when the 63 | .Ql ${ Ns Ar variable Ns } 64 | form to be substituted happens in the middle of a word (with a prefix 65 | and/or a postfix), which means the whole word will be deleted. 66 | If this is not the behaviour you want, use the 67 | .Fl D 68 | option. 69 | .Sh OPTIONS 70 | .Bl -tag -width x 71 | .It Fl D Ar default 72 | If this option is given and 73 | .Ar envvar 74 | is undefined, substitute 75 | .Ar default 76 | for the value of 77 | .Ar variable 78 | instead of no word. 79 | For instance, to substitute the empty word, use 80 | .Ql -D \(dq\(dq . 81 | .It Fl i 82 | Insist. 83 | If 84 | .Ar envvar 85 | is undefined, 86 | .Nm 87 | will not do anything; instead, it will exit 100 with an error message. 88 | This has precedence over any 89 | .Fl D 90 | option. 91 | .It Fl u 92 | Unexport. 93 | .Ar envvar 94 | will be removed from the environment after the substitution. 95 | .Ql importas -u Ar variable Ar envvar 96 | is equivalent to 97 | .Ql importas Ar variable Ar envvar No unexport Ar envvar . 98 | .El 99 | .Pp 100 | Other options are used to control 101 | the substitution mechanism 102 | .Po 103 | cf.\& 104 | .Xr execline-transform 7 105 | .Pc . 106 | .Sh SEE ALSO 107 | .Xr define 1 , 108 | .Xr elgetpositionals 1 , 109 | .Xr elglob 1 , 110 | .Xr multidefine 1 , 111 | .Xr multisubstitute 1 , 112 | .Xr exec 3 , 113 | .Xr execline-substitute 7 , 114 | .Xr execline-transform 7 115 | .Pp 116 | This man page is ported from the authoritative documentation at: 117 | .Lk https://skarnet.org/software/execline/importas.html 118 | .Sh AUTHORS 119 | .An Laurent Bercot 120 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 121 | -------------------------------------------------------------------------------- /man1/dollarat.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt DOLLARAT 1 3 | .Os 4 | .Sh NAME 5 | .Nm dollarat 6 | .Nd print the positional parameters of an execline script 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl n 10 | .Op Fl 0 | Fl d Ar delimchar 11 | .Sh DESCRIPTION 12 | .Nm 13 | reads the number 14 | .Ar n 15 | of 16 | .Dq positional parameters 17 | in the 18 | .Ev \&# 19 | environment variable. 20 | If that variable is not set or does not contain a valid 21 | .Ar n , 22 | .Nm dollarat 23 | exits 100. 24 | .Pp 25 | .Nm 26 | prints the value of the 27 | .Ev 1 28 | environment variable, then 29 | .Ar delimchar , 30 | then the value of the 31 | .Ev 2 32 | environment variable... and so on until 33 | .Ar n . 34 | If one of these variables is not set, 35 | .Nm 36 | exits 100. 37 | .Pp 38 | If everything runs OK, 39 | .Nm 40 | exits 0. 41 | This makes it one of the rare 42 | .Dq exiting 43 | execline commands. 44 | .Pp 45 | You can use 46 | .Ql dollarat -d \(dq\(dq 47 | along with the 48 | .Xr forbacktickx 1 49 | command to reliably loop over the positional parameters: 50 | .Bd -literal -offset indent 51 | #!/command/execlineb 52 | forbacktickx -d "" ARG { dollarat -d "" } 53 | dosomething $ARG 54 | .Ed 55 | .Pp 56 | will call 57 | .Ql dosomething 58 | in turn on each argument to the script. 59 | That will work even if those arguments contain spaces, newlines, or 60 | other fancy characters. 61 | .Pp 62 | Alternatively, instead of encoding data into a netstring, you can use 63 | a null-separated list, which will work the same way: 64 | .Bd -literal -offset indent 65 | #!/command/execlineb 66 | forbacktickx -0 ARG { dollarat -0 } 67 | dosomething $ARG 68 | .Ed 69 | .Sh OPTIONS 70 | .Bl -tag -width x 71 | .It Fl n 72 | .Em chomp . 73 | Do not print the last 74 | .Ar delimchar . 75 | .It Fl d Ar delimchar 76 | Use the character 77 | .Ar delimchar 78 | as separator between the arguments. 79 | Default: 80 | .Ql \en . 81 | If 82 | .Ar delimchar 83 | has more than one character, only the first one is used. 84 | If 85 | .Ar delimchar 86 | is the empty string, then 87 | .Nm 88 | will output the positional parameters as a sequence of netstrings 89 | .Po 90 | cf. 91 | .Xr execline-transform 7 92 | .Pc 93 | and the 94 | .Fl n 95 | option will be ignored. 96 | .It Fl 0 97 | Use the null character as separator. 98 | If this option and the 99 | .Fl d 100 | option are given concurrently, the rightmost one wins. 101 | Warning: 102 | .Fl 0 103 | should only be used to feed data to programs that know how to handle 104 | null-separated lists. 105 | .El 106 | .Sh SEE ALSO 107 | .Xr elgetopt 1 , 108 | .Xr forbacktickx 1 , 109 | .Xr shift 1 , 110 | .Xr execline-transform 7 111 | .Pp 112 | This man page is ported from the authoritative documentation at: 113 | .Lk https://skarnet.org/software/execline/dollarat.html 114 | .Sh AUTHORS 115 | .An Laurent Bercot 116 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 117 | -------------------------------------------------------------------------------- /man1/forx.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt FORX 1 3 | .Os 4 | .Sh NAME 5 | .Nm forx 6 | .Nd run a loop 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl E | Fl e 14 | .Op Fl p 15 | .Op Fl o Ar okcodes | Fl x Ar breakcodes 16 | .Ar variable 17 | { 18 | .Ar args... 19 | } 20 | .Ar loop... 21 | .Sh DESCRIPTION 22 | .Nm 23 | reads a block 24 | .Po 25 | cf.\& 26 | .Xr execline-block 7 27 | .Pc 28 | and unquotes it. 29 | That block contains a list of 30 | .Ar args . 31 | .Pp 32 | For each argument 33 | .Ar x 34 | in 35 | .Ar args... , 36 | .Nm 37 | runs 38 | .Ar loop 39 | as a child process, with 40 | .Sm off 41 | .Ar variable 42 | = 43 | .Ar x 44 | .Sm on 45 | added to its environment. 46 | .Pp 47 | .Nm 48 | then exits 0. 49 | .Pp 50 | You can start 51 | .Ar loop 52 | with 53 | .Ql importas -u Ar variable Ar variable 54 | if you want variable substitution. 55 | .Sh OPTIONS 56 | .Bl -tag -width x 57 | .It Fl o Ar okcodes 58 | .Ar okcodes 59 | must be a comma-separated list of exit codes. 60 | If 61 | .Ar loop 62 | exits with one of the codes in 63 | .Ar okcodes , 64 | .Nm 65 | will run the following instances of the loop, but if the exit code is 66 | not listed in 67 | .Ar okcodes , 68 | .Nm 69 | will exit immediately with an approximation 70 | .Po 71 | cf.\& 72 | .Xr execline-exitcodes 7 73 | .Pc 74 | of the same exit code. 75 | .It Fl x Ar breakcodes 76 | Like the previous option, but with inverted meaning - the listed exit 77 | codes are codes that will make 78 | .Nm 79 | break the loop and exit, and the unlisted exit codes will make it keep 80 | looping. 81 | .It Fl p 82 | Run in parallel. 83 | Do not wait for an instance of 84 | .Ar loop... 85 | to exit before spawning the next one. 86 | .Nm 87 | will still wait for all instances of 88 | .Ar loop 89 | to terminate before exiting 0. 90 | If the 91 | .Fl o 92 | option has been given, 93 | .Nm 94 | will exit 0 if all of the exit codes are in the values listed in the 95 | .Ar okcodes 96 | list, else it will exit 1. 97 | If the 98 | .Fl x 99 | option has been given, 100 | .Nm 101 | will exit 0 if none of the exit codes are in the values listed in the 102 | .Ar breakcodes 103 | list, else it will exit 1. 104 | .It Fl e 105 | No autoimport. 106 | This is the default. 107 | .It Fl E 108 | Autoimport. 109 | Instead of spawning 110 | .Ar loop... , 111 | spawn 112 | .Ql importas -ui Ar variable Ar variable Ar loop... . 113 | This substitutes 114 | .Ar variable 115 | into the command line instead of putting it into the environment. 116 | .El 117 | .Sh SEE ALSO 118 | .Xr execlineb 1 , 119 | .Xr forbacktickx 1 , 120 | .Xr forstdin 1 , 121 | .Xr loopwhilex 1 , 122 | .Xr execline-block 7 , 123 | .Xr execline-exitcodes 7 124 | .Pp 125 | This man page is ported from the authoritative documentation at: 126 | .Lk https://skarnet.org/software/execline/forx.html 127 | .Sh AUTHORS 128 | .An Laurent Bercot 129 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 130 | -------------------------------------------------------------------------------- /man1/backtick.1: -------------------------------------------------------------------------------- 1 | .Dd February 16, 2021 2 | .Dt BACKTICK 1 3 | .Os 4 | .Sh NAME 5 | .Nm backtick 6 | .Nd run a program and stores its output in an environment variable, then execute another program 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Nm 12 | .Op Fl i | Fl I | Fl x | Fl D Ar default 13 | .Op Fl N | Fl n 14 | .Op [ -E | -e 15 | .Ar variable 16 | { 17 | .Ar prog1... 18 | } 19 | .Ar prog2... 20 | .Sh DESCRIPTION 21 | .Nm 22 | reads 23 | .Ar prog1... 24 | in an 25 | .Xr execline-block 7 26 | and unquotes it. 27 | .Pp 28 | It runs 29 | .Ar prog1... 30 | as a child process and saves its output in memory. 31 | This output must not contain a null character. 32 | .Pp 33 | .Nm 34 | .Xr exec 3 Ns 35 | s into 36 | .Ar prog2... , 37 | with 38 | .Ar variable 39 | added to the environment with 40 | .Ar prog1... Ap 41 | s output as a value. 42 | .Sh OPTIONS 43 | .Bl -tag -width x 44 | .It Fl N 45 | Store 46 | .Ar prog1... Ap 47 | s output as is, including the last newline, if any. 48 | .It Fl n 49 | Chomp an ending newline off 50 | .Ar prog1... Ap 51 | s output. 52 | This is the default. 53 | .It Fl e 54 | No autoimport. 55 | This is the default. 56 | .It Fl E 57 | Autoimport. 58 | Instead of 59 | .Xr exec 3 Ns 60 | ing into 61 | .Ar prog2... , 62 | .Xr exec 3 63 | into 64 | .Ql importas -ui Ar variable Ar variable Ar prog2... . 65 | This substitutes 66 | .Ar variable 67 | into the command line instead of putting it into the environment. 68 | .El 69 | .Pp 70 | The other options tell 71 | .Nm 72 | what to do if 73 | .Ar prog1... Ap 74 | s output is not suitable as the contents of an environment variable 75 | (i.e. it contains a null character) or if 76 | .Ar prog1... 77 | crashes or exits nonzero: 78 | .Bl -tag -width x 79 | .It Fl i 80 | .Nm 81 | exits with an approximation 82 | .Po 83 | cf.\& 84 | .Xr execline-exitcodes 7 85 | .Pc 86 | of 87 | .Ar prog1 Ap 88 | s exit code, or 124 if 89 | .Ar prog1 90 | wrote a null character. 91 | This is the default. 92 | .It Fl I 93 | The value of 94 | .Ar variable 95 | is set to whatever the start of 96 | .Ar prog1... Ap 97 | s output is, up to the first null character, or to whatever 98 | .Ar prog1... 99 | wrote before crashing; chomping is applied if required; then execution 100 | proceeds. 101 | .It Fl x 102 | .Ar variable 103 | is 104 | .Sy removed 105 | from the environment, and execution proceeds. 106 | .It Fl D Ar default 107 | The value of 108 | .Ar variable 109 | is set to 110 | .Ar default , 111 | and execution proceeds. 112 | .El 113 | .Sh SEE ALSO 114 | .Xr background 1 , 115 | .Xr foreground 1 , 116 | .Xr if 1 , 117 | .Xr ifelse 1 , 118 | .Xr ifte 1 , 119 | .Xr ifthenelse 1 , 120 | .Xr pipeline 1 , 121 | .Xr runblock 1 , 122 | .Xr execline-block 7 123 | .Pp 124 | This man page is ported from the authoritative documentation at: 125 | .Lk https://skarnet.org/software/execline/backtick.html 126 | .Sh AUTHORS 127 | .An Laurent Bercot 128 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 129 | -------------------------------------------------------------------------------- /man1/multidefine.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt MULTIDEFINE 1 3 | .Os 4 | .Sh NAME 5 | .Nm multidefine 6 | .Nd split a value and defines several variables at once, then execute another program 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl 0 14 | .Op Fl r 15 | .Op Fl C | Fl c 16 | .Op Fl N | Fl n 17 | .Op Fl d Ar delim 18 | .Ar value 19 | { 20 | .Ar variables... 21 | } 22 | .Ar prog... 23 | .Sh DESCRIPTION 24 | .Nm 25 | reads a block 26 | .Po 27 | cf.\& 28 | .Xr execline-block 7 29 | .Pc 30 | containing a list of variables. 31 | That block must not be empty. 32 | .Pp 33 | .Nm 34 | splits 35 | .Po 36 | cf.\& 37 | .Xr execline-transform 7 38 | .Pc 39 | .Ar value , 40 | and performs other operations depending on the given options. 41 | .Pp 42 | .Nm 43 | performs parallel substitution 44 | .Po 45 | cf.\& 46 | .Xr execline-substitute 7 47 | .Pc 48 | on 49 | .Ar prog... , 50 | using all of the 51 | .Ar variables 52 | in the block as keys. 53 | The first word in the split 54 | .Ar value 55 | is assigned to the first 56 | .Ar variable , 57 | the second word is assigned to the second 58 | .Ar variable , 59 | and so on. 60 | Every 61 | .Ar variable 62 | is substituted with exactly one word. 63 | .Pp 64 | If a 65 | .Ar variable 66 | is the empty word, then the word in the split 67 | .Ar value 68 | corresponding to its position is not substituted. 69 | So you can use empty words to pad the list of variables and only 70 | perform substition on the relevant fields. 71 | .Pp 72 | .Nm 73 | then 74 | .Xr exec 3 Ns 75 | s into the modified 76 | .Ar prog... . 77 | .Sh OPTIONS 78 | .Bl -tag -width x 79 | .It Fl 0 80 | If there are more 81 | .Ar variables 82 | in the block than there are words in the split 83 | .Ar value , 84 | the excess variables will be replaced with zero word. 85 | Without this option, the excess variables are replaced with the empty 86 | word. 87 | .It Fl r 88 | Behave similarly to the 89 | .Dq read 90 | shell command. 91 | If there are more words in the split 92 | .Ar value 93 | than there are 94 | .Ar variables 95 | in the block, the last variable will be replaced with all the 96 | remaining words (and will be split). 97 | Without this option, the last variable is replaced with a single word, 98 | and the excess words are lost. 99 | .El 100 | .Pp 101 | Other options are used to control 102 | .Po 103 | cf.\& 104 | .Xr execline-transform 7 105 | .Pc 106 | the substitution mechanism. 107 | Note that the value is always split. 108 | .Sh SEE ALSO 109 | .Xr define 1 , 110 | .Xr elgetpositionals 1 , 111 | .Xr elglob 1 , 112 | .Xr execlineb 1 , 113 | .Xr importas 1 , 114 | .Xr multisubstitute 1 , 115 | .Xr exec 3 , 116 | .Xr execline-block 7 , 117 | .Xr execline-substitute 7 , 118 | .Xr execline-transform 7 119 | .Pp 120 | This man page is ported from the authoritative documentation at: 121 | .Lk https://skarnet.org/software/execline/multidefine.html 122 | .Sh AUTHORS 123 | .An Laurent Bercot 124 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 125 | -------------------------------------------------------------------------------- /man1/elgetpositionals.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt ELGETPOSITIONALS 1 3 | .Os 4 | .Sh NAME 5 | .Nm elgetpositionals 6 | .Nd substitute the positional parameters of an execline script 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl P Ar sharp 10 | .Ar prog... 11 | .Sh DESCRIPTION 12 | .Nm 13 | reads the number 14 | .Ar n 15 | of 16 | .Dq positional parameters 17 | in the 18 | .Ev \&# 19 | environment variable. 20 | If that variable is not set or does not contain a valid 21 | .Ar n , 22 | .Nm 23 | exits 100. 24 | .Pp 25 | .Nm 26 | performs some substitutions 27 | .Po 28 | cf. 29 | .Xr execline-substitute 7 30 | .Pc 31 | in parallel on 32 | .Ar prog... : 33 | .Bl -bullet -width x 34 | .It 35 | key: 36 | .Ql # , 37 | value: 38 | .Ar n 39 | .It 40 | key: 41 | .Ql 0 , 42 | value: the value of the 43 | .Ev 0 44 | environment variable 45 | .It 46 | key: 47 | .Ql 1 , 48 | value: the value of the 49 | .Ev 1 50 | environment variable 51 | .It 52 | \&... and so on until 53 | .Ar n 54 | .Po 55 | or 56 | .Ar sharp 57 | if it is greater than 58 | .Ar n 59 | .Pc . 60 | Those values are never transformed. 61 | .It 62 | key: 63 | .Ql @ , 64 | value: all values of the variables from 65 | .Ql 1 66 | to 67 | .Ar n . 68 | This value is split 69 | .Po 70 | cf. 71 | .Xr execline-transform 7 72 | .Pc 73 | into 74 | .Ar n 75 | words. 76 | .El 77 | .Pp 78 | If a variable between 79 | .Ql 0 80 | and 81 | .Ar n 82 | does not exist, 83 | .Nm 84 | exits 100. 85 | .Pp 86 | A typical argument-taking execline script will often begin this way: 87 | .Bd -literal -offset indent 88 | #!/command/execlineb 89 | elgetopt optstring 90 | elgetpositionals 91 | prog... 92 | .Ed 93 | .Pp 94 | If you are performing other substitutions that do not depend on the 95 | positional parameters, think about replacing the 96 | .Nm 97 | call with a 98 | .Xr multisubstitute 1 99 | call containing the 100 | .Ql elgetpositionals 101 | directive. 102 | .Pp 103 | If you are going to use the 104 | .Xr shift 1 105 | command, it is best to use 106 | .Xr importas 1 107 | to substitute the first positional parameters, then use 108 | .Xr shift 1 , 109 | then 110 | .Nm . 111 | That way, 112 | .Ql $@ 113 | will correctly be replaced by the remaining arguments. 114 | More generally, you should try to use 115 | .Nm 116 | as late as possible. 117 | .Pp 118 | Use 119 | .Xr execlineb 1 Ap 120 | s 121 | .Fl S 122 | switch instead of 123 | .Nm 124 | whenever you can. 125 | It is more efficient. 126 | .Sh OPTIONS 127 | .Bl -tag -width x 128 | .It Fl P Ar sharp 129 | Substitute at least 130 | .Ar sharp Ns 131 | +1 positional parameters, from 0 to 132 | .Fn max n sharp . 133 | If 134 | .Ar n 135 | < 136 | .Ar sharp , 137 | positional parameters between 138 | .Ar n Ns 139 | +1 and 140 | .Ar sharp 141 | are replaced with the empty string. 142 | Not having the 143 | .Fl P 144 | switch is equivalent to having 145 | .Ql -P 0 . 146 | .El 147 | .Sh SEE ALSO 148 | .Xr define 1 , 149 | .Xr elglob 1 , 150 | .Xr execlineb 1 , 151 | .Xr importas 1 , 152 | .Xr multidefine 1 , 153 | .Xr multisubstitute 1 , 154 | .Xr shift 1 , 155 | .Xr execline-substitute 7 , 156 | .Xr execline-transform 7 157 | .Pp 158 | This man page is ported from the authoritative documentation at: 159 | .Lk https://skarnet.org/software/execline/elgetpositionals.html 160 | .Sh AUTHORS 161 | .An Laurent Bercot 162 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 163 | -------------------------------------------------------------------------------- /man1/execline.1: -------------------------------------------------------------------------------- 1 | .Dd February 19, 2023 2 | .Dt EXECLINE 1 3 | .Os 4 | .Sh NAME 5 | .Nm execline 6 | .Nd multicall binary for the execline suite 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar subcommand 10 | .Ar subcommand_arguments... 11 | .Sh DESCRIPTION 12 | The 13 | .Nm 14 | program is only available when the 15 | .Ql --enable-multicall 16 | option has been given to the 17 | .Pa configure 18 | program at build time. 19 | In this configuration, 20 | .Nm 21 | is a multicall binary implementing the functionality of 22 | .Em all 23 | the programs in the execline package; and the other programs, instead 24 | of being executables of their own, are symbolic links to the 25 | execline binary. 26 | .Pp 27 | .Nm 28 | will run the 29 | .Ar subcommand 30 | with its arguments. 31 | For instance, 32 | .Ql execline cd / ls 33 | will run the equivalent of the 34 | .Xr execline-cd 1 35 | program, so this command will list the contents of the 36 | .Pa / 37 | directory. 38 | .Pp 39 | Alternatively, if 40 | .Nm 41 | is called with the name of an existing command, it will run the 42 | equivalent of that command. 43 | For instance, if the 44 | .Pa /usr/bin/cd 45 | file is a (hard or symbolic) link to the 46 | .Pa execline 47 | binary, 48 | .Ql /usr/bin/cd / ls 49 | will list the contents of the 50 | .Pa / 51 | directory. 52 | .Pp 53 | The 54 | .Ql --enable-multicall 55 | option is a user-requested feature to save disk space. 56 | Its goal is purely to save disk space; functionality-wise, the 57 | execline package should be the exact same whether it has been built 58 | with 59 | .Ql --enable-multicall 60 | or not. 61 | That means: any execline script should work the exact same way. 62 | .Pp 63 | Multicall binaries have a number of issues, most of them hidden from 64 | regular users. 65 | One user-visible issue is that their behaviour changes depending on 66 | how they are called, which is not good practice (it breaks naming 67 | agnosticism) despite being common in traditional Unix. 68 | Other, more important issues are only visible to software authors and 69 | maintainers: for instance, they make it difficult to add functionality 70 | to a software package without inadvertently blowing up the amount of 71 | RAM used by the software, and they encourage bad engineering practices 72 | to work around specific problems created by this configuration. 73 | .Pp 74 | I am not a fan of multicall binaries at all. 75 | .Pp 76 | However, it just so happens that the execline package already was a 77 | good candidate for a multicall configuration, and several users had 78 | been asking for it (and complaining about the amount of disk space 79 | that the traditional execline package uses). 80 | So I did an experiment, and it turned out that a multicall execline 81 | binary does save a 82 | .Em huge 83 | amount of space. 84 | Depending on your shared/static library configuration and your libc, 85 | the gain in disk space on Linux can range from 66% to 87%! 86 | The results were contrary to my expectations \(em and simply too good 87 | to pass up. 88 | .Pp 89 | So now, the multicall configuration is supported for execline. 90 | Do not expect anything similar for other skarnet.org packages such as 91 | s6[1], because they're not as good candidates and it would require a 92 | tremendous amount of work for less benefit. 93 | .Sh SEE ALSO 94 | [1] 95 | .Lk https://skarnet.org/software/s6/ 96 | .Pp 97 | This man page is ported from the authoritative documentation at: 98 | .Lk https://skarnet.org/software/execline/execline.html 99 | .Sh AUTHORS 100 | .An Laurent Bercot 101 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 102 | -------------------------------------------------------------------------------- /man1/wait.1: -------------------------------------------------------------------------------- 1 | .Dd May 31, 2022 2 | .Dt WAIT 1 3 | .Os 4 | .Sh NAME 5 | .Nm wait 6 | .Nd wait for a set of children, then execute a program 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl I | Fl i 14 | .Op Fl a | Fl o 15 | .Op Fl r | Fl t Ar timeout 16 | { 17 | .Op Ar pids... 18 | } 19 | .Ar prog... 20 | .Sh DESCRIPTION 21 | .Nm 22 | reads a list of 23 | .Ar pids 24 | in a (possibly empty) block 25 | .Po 26 | cf.\& 27 | .Xr execline-block 7 28 | .Pc , 29 | and unquotes it. 30 | .Pp 31 | .Nm 32 | waits for every child whose pid is listed in 33 | .Ar pids... . 34 | If 35 | .Ar pids... 36 | is an empty list, it waits for every child process it has. 37 | .Pp 38 | .Nm 39 | then 40 | .Xr exec 3 Ns 41 | s into 42 | .Ar prog... . 43 | .Pp 44 | For POSIX compatibility[1], 45 | .Nm 46 | also works when it cannot find a block. 47 | In that case, all the options are still supported and have the same 48 | effect, but the rest of the command line is interpreted as 49 | .Ar pids... 50 | arguments and 51 | .Nm 52 | does not execute into a program; instead, it exits with a conforming 53 | exit code. 54 | .Sh OPTIONS 55 | .Bl -tag -width x 56 | .It Fl r 57 | Equivalent to 58 | .Ql -t 0 . 59 | Do not pause: only reap processes that are already dead when 60 | .Nm 61 | is invoked. 62 | .It Fl t Ar timeout 63 | Wait for a maximum of 64 | .Ar timeout 65 | milliseconds. 66 | If there still are living processes among 67 | .Ar pids... 68 | (or among 69 | .Nm Ap 70 | s children if 71 | .Ar pids... 72 | is an empty list), after 73 | .Ar timeout 74 | milliseconds, they will not be reaped. 75 | .It Fl I 76 | Loose. 77 | If 78 | .Nm 79 | times out while waiting for children to die, it will still 80 | .Xr exec 3 81 | into 82 | .Ar prog... . 83 | This is the default. 84 | .It Fl i 85 | Strict. 86 | If 87 | .Nm 88 | times out, it will print an error message and exit 99. 89 | .It Fl o 90 | Wait for 91 | .Em one 92 | of the listed 93 | .Ar pids 94 | - 95 | .Xr exec 3 96 | into 97 | .Ar prog 98 | as soon as one of the listed children dies. 99 | .Po 100 | If no pid is listed, wait for one child to die. 101 | .Pc 102 | The 103 | .Ev !\& 104 | environment variable will be set to the pid that died, and the 105 | .Ev ?\& 106 | environment variable will contain an approximation of its exit code - 107 | refer to 108 | .Xr execline-exitcodes 7 . 109 | If no listed child has died before 110 | .Nm 111 | has to 112 | .Xr exec 3 113 | .Po 114 | either because it timed out or it has no suitable children left 115 | .Pc , 116 | the 117 | .Ev ?\& 118 | and 119 | .Ev !\& 120 | environment variables are unset. 121 | .It Fl a 122 | Wait for 123 | .Em all 124 | of the listed 125 | .Ar pids . 126 | Do not touch the 127 | .Ev !\& 128 | or 129 | .Ev ?\& 130 | variables. 131 | This is the default. 132 | .El 133 | .Sh SEE ALSO 134 | .Xr emptyenv 1 , 135 | .Xr envfile 1 , 136 | .Xr exec 1 , 137 | .Xr execline-cd 1 , 138 | .Xr execline-umask 1 , 139 | .Xr execlineb 1 , 140 | .Xr exit 1 , 141 | .Xr export 1 , 142 | .Xr fdblock 1 , 143 | .Xr fdclose 1 , 144 | .Xr fdmove 1 , 145 | .Xr fdreserve 1 , 146 | .Xr fdswap 1 , 147 | .Xr getcwd 1 , 148 | .Xr getpid 1 , 149 | .Xr heredoc 1 , 150 | .Xr piperw 1 , 151 | .Xr posix-cd 1 , 152 | .Xr posix-umask 1 , 153 | .Xr redirfd 1 , 154 | .Xr trap 1 , 155 | .Xr tryexec 1 , 156 | .Xr unexport 1 , 157 | .Xr withstdinas 1 , 158 | .Xr exec 3 , 159 | .Xr execline-block 7 160 | .Pp 161 | [1] 162 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/utilities/wait.html 163 | .Pp 164 | This man page is ported from the authoritative documentation at: 165 | .Lk https://skarnet.org/software/execline/wait.html 166 | .Sh AUTHORS 167 | .An Laurent Bercot 168 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 169 | -------------------------------------------------------------------------------- /man1/multisubstitute.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt MULTISUBSTITUTE 1 3 | .Os 4 | .Sh NAME 5 | .Nm multisubstitute 6 | .Nd perform several substitutions at once in its 7 | .Ar argv , 8 | then execute another program 9 | .Sh SYNOPSIS 10 | In an 11 | .Xr execlineb 1 12 | script: 13 | .Pp 14 | .Nm 15 | { 16 | .Bd -ragged -compact 17 | .Oo 18 | define 19 | .Op Fl N | Fl n 20 | .Op Fl s 21 | .Op Fl C | Fl c 22 | .Op Fl d Ar delim 23 | .Ar variable 24 | .Ar value 25 | .Oc 26 | .Ed 27 | .Bd -ragged -compact 28 | .Oo 29 | importas 30 | .Op Fl i | Fl D Ar default 31 | .Op Fl N | Fl n 32 | .Op Fl s 33 | .Op Fl C | Fl c 34 | .Op Fl d Ar delim 35 | .Ar variable 36 | .Ar envvar 37 | .Oc 38 | .Ed 39 | .Bd -ragged -compact 40 | .Oo 41 | elglob 42 | .Op Fl v 43 | .Op Fl w 44 | .Op Fl s 45 | .Op Fl m 46 | .Op Fl e 47 | .Op Fl 0 48 | .Ar variable 49 | .Ar pattern 50 | .Oc 51 | .Ed 52 | .Bd -ragged -compact 53 | .Oo 54 | elgetpositionals 55 | .Op Fl P Ar sharp 56 | .Oc 57 | .Ed 58 | .Bd -ragged -compact 59 | .Oo 60 | multidefine 61 | .Ar value 62 | { 63 | .Ar variable... 64 | } 65 | .Oc 66 | .Ed 67 | .Ar ... 68 | .Bd -ragged -compact 69 | } 70 | .Ed 71 | .Bd -ragged -compact 72 | .Ar prog... 73 | .Ed 74 | .Sh DESCRIPTION 75 | .Nm 76 | reads a block 77 | .Po 78 | cf.\& 79 | .Xr execline-block 7 80 | .Pc 81 | containing a series of substitution commands. 82 | It performs all those substitutions 83 | .Po 84 | cf.\& 85 | .Xr execline-substitute 7 86 | .Pc 87 | on 88 | .Ar prog... 89 | in parallel. 90 | Check the relevant documentation page to learn about the syntax of 91 | each substitution command. 92 | .Pp 93 | .Nm 94 | then 95 | .Xr exec 3 Ns 96 | s into the modified 97 | .Ar prog... . 98 | .Sh OPTIONS 99 | If an 100 | .Ql importas 101 | directive was given with the 102 | .Fl i 103 | option, and the looked up variable is undefined, 104 | .Nm 105 | will exit 100. 106 | .Ss Rationale 107 | .Sy Security 108 | .Pp 109 | .Nm 110 | can be used to avoid unwanted 111 | .Em serial substitutions . 112 | Consider the following script: 113 | .Bd -literal -offset indent 114 | #!/command/execlineb 115 | export A wrong 116 | define B ${A} 117 | importas A A 118 | echo ${B} 119 | .Ed 120 | .Pp 121 | Running it will print 122 | .Ql wrong , 123 | because 124 | .Ql A 125 | is substituted 126 | .Em after 127 | B. 128 | On the contrary, the following script: 129 | .Bd -literal -offset indent 130 | #!/command/execlineb 131 | export A wrong 132 | multisubstitute 133 | { 134 | define B ${A} 135 | importas A A 136 | } 137 | echo ${B} 138 | .Ed 139 | .Pp 140 | will print 141 | .Ql ${A} , 142 | because A and B are substituted at the same time. 143 | Serial substitution may be what you want - but when in doubt, always 144 | perform parallel substitution. 145 | .Pp 146 | .Sy Efficiency 147 | .Pp 148 | Substitution 149 | .Po 150 | cf.\& 151 | .Xr execline-substitute 7 152 | .Pc 153 | is a costly mechanism: the whole 154 | .Ar argv 155 | is read three times and rewritten twice. 156 | Serial substitution multiplies the cost by the number of 157 | substitutions, whereas parallel substitution pays the price only once. 158 | .Ss Credits 159 | Paul Jarc[1] first originated the idea of the 160 | .Nm 161 | command and a possible syntax. 162 | .Sh SEE ALSO 163 | .Xr define 1 , 164 | .Xr elgetpositionals 1 , 165 | .Xr elglob 1 , 166 | .Xr execlineb 1 , 167 | .Xr importas 1 , 168 | .Xr multidefine 1 , 169 | .Xr exec 3 , 170 | .Xr execline-block 7 , 171 | .Xr execline-substitute 7 172 | .Pp 173 | [1] 174 | .Lk https://code.dogmap.org/ 175 | .Pp 176 | This man page is ported from the authoritative documentation at: 177 | .Lk https://skarnet.org/software/execline/multisubstitute.html 178 | .Sh AUTHORS 179 | .An Laurent Bercot 180 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 181 | -------------------------------------------------------------------------------- /man7/execline-exitcodes.7: -------------------------------------------------------------------------------- 1 | .Dd March 13, 2022 2 | .Dt EXECLINE-EXITCODES 7 3 | .Os 4 | .Sh NAME 5 | .Nm execline-exitcodes 6 | .Nd how to propagate exit codes up a process dynasty 7 | .Sh DESCRIPTION 8 | Say we have a parent process 9 | .Ql P , 10 | child of a grandparent process 11 | .Ql G , 12 | spawning a child process 13 | .Ql C 14 | and waiting for it. 15 | Either C dies normally with an exit code from 0 to 255, or it is 16 | killed by a signal. 17 | How can we make sure that P reports to G what happened to C, with as 18 | much precision as possible? 19 | .Pp 20 | The problem is, there's more information in a wstat (the structure 21 | filled in by 22 | .Xr waitpid 2 ) 23 | than a process can report by simply exiting. 24 | P could exit with the same exit code as C, but then what should it do 25 | if C has been killed by a signal? 26 | .Pp 27 | An idea is to have P kill itself with the same signal that killed C. 28 | But that's actually not right, because P itself could be killed by a 29 | signal from another source, and G needs that information. 30 | .Dq P has been killed by a signal 31 | and 32 | .Dq C has been killed by a signal 33 | are two different pieces of information, so they should not be 34 | reported in the same way. 35 | .Pp 36 | So, any way you look at it, there is always more information than we 37 | can report. 38 | .Pp 39 | Shells have their own convention[1] for reporting crashes, but since 40 | any exit code greater than 127 is reported as is, the information 41 | given by the shell is unreliable: 42 | .Dq child exited 129 43 | and 44 | .Dq child was killed by SIGHUP 45 | are indistinguishable. 46 | When shells get nested, all bets are off - the information conveyed by 47 | exit codes becomes devoid of meaning pretty fast. 48 | We need something better. 49 | .Ss execline's solution 50 | execline commands such as 51 | .Xr if 1 , 52 | that can report a child's exit code, proceed that way when they're in 53 | the position of P: 54 | .Bl -bullet -width x 55 | .It 56 | If C was killed by a signal: P exits 128 plus the signal number. 57 | .It 58 | If C exited 128 or more: P exits 128. 59 | .It 60 | Else, P exits with the same code as C. 61 | .El 62 | .Pp 63 | Rationale: 64 | .Bl -bullet -width x 65 | .It 66 | 128+ exit codes are extremely rare and should report really 67 | problematic conditions; commands usually exit 127 or less. 68 | If C exits 128+, it's more important to convey the information 69 | .Do 70 | something really bad happened, but the C process itself was not 71 | killed by a signal 72 | .Dc 73 | than the exact nature of the event. 74 | .It 75 | Commands following that convention can be nested. 76 | If P exits 129+, G knows that C was killed by a signal. 77 | If G also needs to report that to its parent, it will exit 128: G's 78 | parent will not know the signal number, but it will know that P 79 | reported 128 or more, so either C or a scion of C had problems. 80 | .It 81 | Exact information is reported in the common case. 82 | .El 83 | .Ss Summary of common exit codes for execline programs 84 | .Bl -tag -width x 85 | .It 0 86 | Success. 87 | This code is rarely encountered, because most execline programs 88 | chainload into something else when they succeed, instead of exiting 0. 89 | .It 100 90 | Wrong usage. 91 | .It 111 92 | System call failed. 93 | .It 126 94 | Unable to chainload into another program 95 | .Po 96 | any other error than 97 | .Dv ENOENT 98 | .Pc . 99 | .It 127 100 | Unable to chainload into another program (executable not found). 101 | .El 102 | .Sh SEE ALSO 103 | .Xr forx 1 , 104 | .Xr waitpid 2 105 | .Pp 106 | [1] 107 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_08_02 108 | .Pp 109 | This man page is ported from the authoritative documentation at: 110 | .Lk https://skarnet.org/software/execline/exitcodes.html 111 | .Sh AUTHORS 112 | .An Laurent Bercot 113 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 114 | -------------------------------------------------------------------------------- /man7/execline-block.7: -------------------------------------------------------------------------------- 1 | .Dd February 16, 2021 2 | .Dt EXECLINE-BLOCK 7 3 | .Os 4 | .Sh NAME 5 | .Nm execline-block 6 | .Nd overview of execline blocks 7 | .Sh DESCRIPTION 8 | A command line (and thus an execline script) is one-dimensional. 9 | But a Unix execution flow can be 10 | .Em two Ns 11 | -dimensional: when two instructions are sequenced, for instance. 12 | In that case, we need a way to extract 13 | .Em two 14 | command lines from 15 | .Em one 16 | argv. 17 | That is precisely what 18 | .Em blocks 19 | are made for. 20 | .Pp 21 | execline commands that need more than one linear set of arguments use 22 | blocks. 23 | For instance, the 24 | .Xr foreground 1 25 | command needs to spawn a first process, then execute into a second one. 26 | It reads the command line for the first process from a block, and the 27 | command line for the second process from the rest of the argv. 28 | In the following script: 29 | .Bd -literal -offset indent 30 | #!/command/execlineb 31 | foreground { echo 1 } echo 2 32 | .Ed 33 | .Pp 34 | .Ql echo 1 35 | is read from a block and spawned; then 36 | .Ql echo 2 37 | is executed. 38 | .Ss execlineb syntax 39 | In 40 | .Xr execlineb 1 41 | scripts, blocks are delimited by braces. 42 | They can be nested. 43 | .Ss argv syntax 44 | .Xr execlineb 1 45 | reads and parses the script, and converts it into an 46 | .Em argv 47 | (a simple Unix command line) with a different syntax for blocks. 48 | In an argv, blocks are not delimited by braces; they are made of 49 | .Em quoted arguments 50 | and terminated by an empty word 51 | .Po 52 | \(dq\(dq 53 | .Pc . 54 | A quoted argument begins with a space. 55 | Nested blocks are represented by arguments being quoted several times, 56 | i.e. having several spaces in front of them; an empty word inside a 57 | block gets quoted too, i.e. it will be represented as a series of 58 | spaces. 59 | .Pp 60 | Actually, the block-reading commands know nothing about braces; 61 | they only understand the 62 | .Dq quoted arguments + empty word 63 | syntax. 64 | So if you want to use 65 | .Xr foreground 1 66 | from your shell to sequence 67 | .Ql echo 1 68 | and 69 | .Ql echo 2 , 70 | you will have to write 71 | .Bd -literal -offset indent 72 | $ foreground ' echo' ' 1' '' echo 2 73 | .Ed 74 | .Pp 75 | You do not really need to quote every argument inside a block in that 76 | simple case. 77 | The following command works as well: 78 | .Bd -literal -offset indent 79 | $ foreground echo 1 '' echo 2 80 | .Ed 81 | .Pp 82 | However, this is bad practice, because it leads to a security hole: 83 | commands that perform substitution 84 | .Po 85 | \&.cf 86 | .Xr execline-substitute 7 87 | .Pc 88 | inside a block may produce empty words, which may modify your script's 89 | execution flow. 90 | .Bd -literal -offset indent 91 | $ define FOO '' foreground ' echo' ' ${FOO}' ' rm' ' -rf' ' /' '' echo blah 92 | .Ed 93 | .Pp 94 | is safe, whereas 95 | .Bd -literal -offset indent 96 | $ define FOO '' foreground echo '${FOO}' rm -rf / '' echo blah 97 | .Ed 98 | .Pp 99 | has very much unwanted results. 100 | (Don't try this at home.) 101 | .Pp 102 | You can use the 103 | .Ev EXECLINE_STRICT 104 | environment variable to check proper block quoting. 105 | If that variable contains 106 | .Ql 1 , 107 | commands that read blocks will print a warning message every time they 108 | find an unquoted argument inside a block. 109 | If that variable contains 110 | .Ql 2 111 | or a bigger integer, commands will print an error message and die on 112 | unquoted arguments. 113 | .Pp 114 | You can use 115 | .Xr execlineb 1 Ap Ns 116 | s 117 | .Fl w 118 | or 119 | .Fl W 120 | switch to set 121 | .Ev EXECLINE_STRICT 122 | to 123 | .Ql 1 124 | or 125 | .Ql 2 . 126 | .Sh SEE ALSO 127 | .Xr execlineb 1 , 128 | .Xr foreground 1 , 129 | .Xr execline-substitute 7 130 | .Pp 131 | This man page is ported from the authoritative documentation at: 132 | .Lk https://skarnet.org/software/execline/el_semicolon.html.html 133 | .Sh AUTHORS 134 | .An Laurent Bercot 135 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 136 | -------------------------------------------------------------------------------- /man1/redirfd.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt REDIRFD 1 3 | .Os 4 | .Sh NAME 5 | .Nm redirfd 6 | .Nd redirect a given file descriptor to a file, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl r | Fl w | Fl u | Fl a | Fl x 10 | .Op Fl n 11 | .Op Fl b 12 | .Ar fd 13 | .Ar file 14 | .Ar prog... 15 | .Sh DESCRIPTION 16 | .Nm 17 | redirects the file descriptor number 18 | .Ar fd 19 | to 20 | .Ar file , 21 | then 22 | .Xr exec 3 Ns 23 | s into 24 | .Ar prog... . 25 | .Bl -bullet -width x 26 | .It 27 | .Ql redirfd -r Ar n Ar file No prog... 28 | is roughly equivalent to 29 | .Ql sh -c 'exec prog... Ar n Ns < Ns Ar file' 30 | .It 31 | .Ql redirfd -w Ar n Ar file No prog... 32 | is roughly equivalent to 33 | .Ql sh -c 'exec prog... Ar n Ns > Ns Ar file' 34 | .It 35 | .Ql redirfd -u Ar n Ar file No prog... 36 | is roughly equivalent to 37 | .Ql sh -c 'exec prog... Ar n Ns <> Ns file' 38 | .It 39 | .Ql redirfd -a Ar n Ar file No prog... 40 | is roughly equivalent to 41 | .Ql sh -c 'exec prog... Ar n Ns >> Ns Ar file' 42 | .It 43 | .Ql redirfd -x Ar n Ar file No prog... 44 | has no portable shell equivalent. 45 | .El 46 | .Ss Special fifo handling 47 | The 48 | .Fl n 49 | and 50 | .Fl b 51 | options are especially useful with named pipes. 52 | .Bl -bullet -width x 53 | .It 54 | Opening a fifo for reading, blocking if there is no writer: 55 | .Bd -ragged -offset indent 56 | redirfd -r 57 | .Ar n 58 | .Ar fifo 59 | prog... 60 | .Ed 61 | .It 62 | Opening a fifo for reading, with instant success even if there is no 63 | writer, and blocking at the first attempt to read from it: 64 | .Bd -ragged -offset indent 65 | redirfd -r -nb 66 | .Ar n 67 | .Ar fifo 68 | prog... 69 | .Ed 70 | .It 71 | Opening a fifo for writing, blocking if there is no reader: 72 | .Bd -ragged -offset indent 73 | redirfd -w 74 | .Ar n 75 | .Ar fifo 76 | prog... 77 | .Ed 78 | .It 79 | Opening a fifo for writing, with instant success even if there is no 80 | reader: 81 | .Bd -ragged -offset indent 82 | redirfd -w -nb 83 | .Ar n 84 | .Ar fifo 85 | prog... . 86 | .Ed 87 | .Pp 88 | Warning: the first attempt to write to the fifo will raise a 89 | .Dv SIGPIPE 90 | if there is still no reader at that time. 91 | The named pipe semantics normally do not allow a fifo to be open for 92 | writing without a reading end, and you should know what you are doing 93 | if you're using 94 | .Nm 95 | this way. 96 | .El 97 | .Sh OPTIONS 98 | One and only one of the 99 | .Fl r , 100 | .Fl w , 101 | .Fl u 102 | .Fl a , 103 | or 104 | .Fl x 105 | options must be given; the 106 | .Fl n 107 | and 108 | .Fl b 109 | options may be added in any case. 110 | .Bl -tag -width x 111 | .It Fl r 112 | Open 113 | .Ar file 114 | for reading. 115 | .It Fl w 116 | Open 117 | .Ar file 118 | for writing, truncating it if it already exists. 119 | .It Fl u 120 | Open 121 | .Ar file 122 | for reading and writing. 123 | .It Fl a 124 | Open 125 | .Ar file 126 | for appending, creating it if it doesn't exist. 127 | .It Fl x 128 | Open 129 | .Ar file 130 | for writing, creating it, failing if it already exists. 131 | .It Fl n 132 | Open 133 | .Ar file 134 | in non-blocking mode. 135 | .It Fl b 136 | Change mode of 137 | .Ar file 138 | after opening it: 139 | to non-blocking mode if the 140 | .Fl n 141 | option was not given, to blocking mode if it was. 142 | .El 143 | .Sh SEE ALSO 144 | .Xr emptyenv 1 , 145 | .Xr envfile 1 , 146 | .Xr exec 1 , 147 | .Xr execline-cd 1 , 148 | .Xr execline-umask 1 , 149 | .Xr exit 1 , 150 | .Xr export 1 , 151 | .Xr fdblock 1 , 152 | .Xr fdclose 1 , 153 | .Xr fdmove 1 , 154 | .Xr fdreserve 1 , 155 | .Xr fdswap 1 , 156 | .Xr getcwd 1 , 157 | .Xr getpid 1 , 158 | .Xr heredoc 1 , 159 | .Xr piperw 1 , 160 | .Xr posix-cd 1 , 161 | .Xr posix-umask 1 , 162 | .Xr trap 1 , 163 | .Xr tryexec 1 , 164 | .Xr unexport 1 , 165 | .Xr wait 1 , 166 | .Xr withstdinas 1 , 167 | .Xr exec 3 168 | .Pp 169 | This man page is ported from the authoritative documentation at: 170 | .Lk https://skarnet.org/software/execline/redirfd.html 171 | .Sh AUTHORS 172 | .An Laurent Bercot 173 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 174 | -------------------------------------------------------------------------------- /man1/forstdin.1: -------------------------------------------------------------------------------- 1 | .Dd September 28, 2021 2 | .Dt FORSTDIN 1 3 | .Os 4 | .Sh NAME 5 | .Nm forstdin 6 | .Nd use input as loop elements to run another program 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl E | Fl e 14 | .Op Fl p | Fl o Ar okcodes | Fl x Ar breakcodes 15 | .Op Fl N | Fl n 16 | .Op Fl C | Fl c 17 | .Op Fl 0 | Fl d Ar delim 18 | .Ar variable 19 | .Ar loop... 20 | .Sh DESCRIPTION 21 | .Nm 22 | reads its standard input as it becomes available, splitting 23 | .Po 24 | cf.\& 25 | .Xr execline-transform 7 26 | .Pc 27 | it on every line automatically. 28 | .Pp 29 | For every argument 30 | .Ar x 31 | in the split output, 32 | .Nm 33 | runs 34 | .Ar loop... 35 | as a child process, with 36 | .Sm off 37 | .Ar variable 38 | = 39 | .Ar x 40 | .Sm on 41 | added to its environment. 42 | .Nm 43 | then exits 0 if it has read something on stdin, and 1 if it hasn't 44 | read anything. 45 | .Pp 46 | You can start 47 | .Ar loop... 48 | with 49 | .Ql importas -u Ar variable Ar variable 50 | to perform variable substitution. 51 | .Sh OPTIONS 52 | .Bl -tag -width x 53 | .It Fl p 54 | Parallel mode. 55 | Do not wait for a 56 | .Ar loop... 57 | instance to finish before spawning the next one. 58 | .Nm 59 | will still wait for all instances of 60 | .Ar loop 61 | to terminate before exiting, though. 62 | .It Fl o Ar okcodes 63 | .Ar okcodes 64 | must be a comma-separated list of exit codes. 65 | If the 66 | .Fl p 67 | flag hasn't been given and 68 | .Ar loop 69 | exits with one of the codes in 70 | .Ar okcodes , 71 | .Nm 72 | will run the following instances of the loop, but if the exit code is 73 | not listed in 74 | .Ar okcodes , 75 | .Nm 76 | will exit immediately with an approximation 77 | .Po 78 | cf.\& 79 | .Xr execline-exitcodes 7 80 | .Pc 81 | of the same exit code. 82 | .It Fl x Ar breakcodes 83 | Like the previous option, but with inverted meaning - the listed exit 84 | codes are codes that will make 85 | .Nm 86 | break the loop and exit, and the unlisted exit codes will make it keep 87 | looping. 88 | .It Fl e 89 | No autoimport. 90 | This is the default. 91 | .It Fl E 92 | Autoimport. 93 | Instead of spawning 94 | .Ar loop... , 95 | spawn 96 | .Ql importas -ui Ar variable Ar variable Ar loop... . 97 | This substitutes 98 | .Ar variable 99 | into the command line instead of putting it into the environment. 100 | .El 101 | .Pp 102 | Other options are similar (in name and functionality) to the switches 103 | passed to control a substitution mechanism 104 | .Po 105 | cf.\& 106 | .Xr execline-transform 7 107 | .Pc , 108 | on purpose; however, 109 | .Nm 110 | does not call the substitution mechanism and has its own semantics for 111 | those options. 112 | .Bl -tag -width x 113 | .It Fl N 114 | Store the whole line in 115 | .Ar variable , 116 | including the terminating newline (or other delimiter). 117 | .It Fl n 118 | Chomp a terminating delimiter from the line from stdin before storing 119 | it into 120 | .Ar variable . 121 | This is the default. 122 | Note that if chomping is active, and the last line of stdin is not 123 | terminated by a delimiter, then this last line will not be processed. 124 | .It Fl C 125 | Crunch. 126 | If there is an empty line (i.e. that only contains a delimiter), do 127 | not call 128 | .Ar loop . 129 | .It Fl c 130 | Do not crunch, call 131 | .Ar loop 132 | even if the line is empty. 133 | This is the default. 134 | .It Fl 0 135 | Accept null characters on its stdin, using them as delimiters. 136 | If this option and a 137 | .Fl d 138 | option are used simultaneously, the rightmost one wins. 139 | .It Fl d Ar delim 140 | Use the characters in string 141 | .Ar delim 142 | as delimiters for a line. 143 | Default is 144 | .Ql \en , 145 | meaning the input is only split on newlines. 146 | .El 147 | .Sh SEE ALSO 148 | .Xr execlineb 1 , 149 | .Xr forbacktickx 1 , 150 | .Xr forx 1 , 151 | .Xr loopwhilex 1 , 152 | .Xr execline-exitcodes 7 , 153 | .Xr execline-transform 7 154 | .Pp 155 | This man page is ported from the authoritative documentation at: 156 | .Lk https://skarnet.org/software/execline/forstdin.html 157 | .Sh AUTHORS 158 | .An Laurent Bercot 159 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 160 | -------------------------------------------------------------------------------- /man1/envfile.1: -------------------------------------------------------------------------------- 1 | .Dd September 29, 2021 2 | .Dt ENVFILE 1 3 | .Os 4 | .Sh NAME 5 | .Nm envfile 6 | .Nd read a file containing variable assignments, add the variables to the environment, then execute a program 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl i | Fl I 10 | .Ar file 11 | .Ar prog... 12 | .Sh DESCRIPTION 13 | .Nm 14 | reads 15 | .Ar file 16 | and adds the key-value pairs defined in 17 | .Ar file 18 | to the environment. 19 | Then it execs into 20 | .Ar prog... , 21 | i.e. the rest of its command line, with the modified environment. 22 | .Ss File syntax 23 | .Ar file 24 | is a text file containing lines of the form 25 | .Ql key = value . 26 | Whitespace is permitted before and after 27 | .Ar key , 28 | and before or after 29 | .Ar value . 30 | .Pp 31 | Empty lines, or lines containing only whitespace, are ignored. 32 | Lines beginning with 33 | .Ql # 34 | (possibly after some whitespace) are ignored (and typically used for 35 | comments). 36 | Leading and trailing whitespace is stripped from values; but a value 37 | can be double-quoted, which allows for inclusion of leading and 38 | trailing whitespace. 39 | .Pp 40 | A non-commented line that ends with a backslash 41 | .Po 42 | .Dq \e 43 | .Pc 44 | is concatenated with the following one, and the newline character is 45 | ignored. 46 | If a backslashed newline happens before the start of a value, then the 47 | whitespace at the beginning of the new line will be part of the value 48 | (i.e. leading whitespace on a new line is not stripped). 49 | .Pp 50 | C escapes, including hexadecimal and octal sequences, are supported in 51 | quoted values. 52 | Unicode codepoint sequences are not supported. 53 | It is possible to include a newline in a quoted value by using 54 | .Ql \en ; 55 | but including newlines in environment variables is not recommended. 56 | .Pp 57 | If 58 | .Ar value 59 | is empty, 60 | .Ar key 61 | is 62 | .Sy still 63 | added to the environment, with an empty value. 64 | If you do not want 65 | .Ar key 66 | to be added to the environment at all, comment out the line. 67 | .Nm 68 | does not offer a way to 69 | .Em remove 70 | variables from the environment. 71 | .Pp 72 | The 73 | .Nm 74 | format is largely compatible with systemd's EnvironmentFile[1] format, 75 | which allows for the reuse of such files outside of systemd. 76 | .Pp 77 | If 78 | .Ar file 79 | is 80 | .Ql - 81 | then 82 | .Nm 83 | reads and parses its standard input instead. 84 | To read a file literally named 85 | .Ql - , 86 | you can use 87 | .Ql ./- 88 | for instance. 89 | .Pp 90 | The variables that can be defined with 91 | .Nm 92 | are purposefully restricted. 93 | If you need more expressive power for your variable names, or for your 94 | values, you should use an envdir instead: see 95 | .Xr s6-envdir 8 . 96 | .Sh OPTIONS 97 | .Bl -tag -width x 98 | .It Fl i 99 | Strict. 100 | If 101 | .Ar file 102 | does not exist, exit 111 with an error message. 103 | This is the default. 104 | .It Fl I 105 | Loose. 106 | If 107 | .Ar file 108 | does not exist, 109 | .Xr exec 3 110 | into 111 | .Ar prog 112 | without modifying the environment. 113 | .El 114 | .Sh EXIT STATUS 115 | .Bl -tag -width x 116 | .It 1 117 | Syntax error in 118 | .Ar file . 119 | .It 100 120 | Wrong usage. 121 | .It 111 122 | System call failed. 123 | .It 126 124 | .Xr execve 2 125 | on 126 | .Ar prog 127 | failed (unknown reason). 128 | .It 127 129 | .Xr execve 2 130 | on 131 | .Ar prog 132 | failed 133 | .Po 134 | .Ar prog 135 | could not be found. 136 | .Pc 137 | .El 138 | .Pp 139 | 0 is not listed because on success, 140 | .Nm 141 | does not exit: it execs into 142 | .Ar prog . 143 | .Sh SEE ALSO 144 | .Xr emptyenv 1 , 145 | .Xr exec 1 , 146 | .Xr execline-cd 1 , 147 | .Xr execline-umask 1 , 148 | .Xr exit 1 , 149 | .Xr export 1 , 150 | .Xr fdblock 1 , 151 | .Xr fdclose 1 , 152 | .Xr fdmove 1 , 153 | .Xr fdreserve 1 , 154 | .Xr fdswap 1 , 155 | .Xr getcwd 1 , 156 | .Xr getpid 1 , 157 | .Xr heredoc 1 , 158 | .Xr piperw 1 , 159 | .Xr posix-cd 1 , 160 | .Xr posix-umask 1 , 161 | .Xr redirfd 1 , 162 | .Xr trap 1 , 163 | .Xr tryexec 1 , 164 | .Xr unexport 1 , 165 | .Xr wait 1 , 166 | .Xr withstdinas 1 , 167 | .Xr execve 2 , 168 | .Xr exec 3 , 169 | .Xr s6-envdir 8 170 | .Pp 171 | [1] 172 | .Lk https://www.freedesktop.org/software/systemd/man/systemd.exec.html#EnvironmentFile= 173 | .Pp 174 | This man page is ported from the authoritative documentation at: 175 | .Lk https://skarnet.org/software/execline/envfile.html 176 | .Sh AUTHORS 177 | .An Laurent Bercot 178 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 179 | -------------------------------------------------------------------------------- /man1/forbacktickx.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt FORBACKTICKX 1 3 | .Os 4 | .Sh NAME 5 | .Nm forbacktickx 6 | .Nd run a program and use its output as loop elements to run another program 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl E | Fl e 14 | .Op Fl p | Fl o Ar okcodes | Fl x Ar breakcodes 15 | .Op Fl N | Fl n 16 | .Op Fl C | Fl c 17 | .Op Fl 0 | Fl d Ar delim 18 | .Ar variable 19 | { 20 | .Ar gen... 21 | } 22 | .Ar loop... 23 | .Sh DESCRIPTION 24 | .Nm 25 | reads a block 26 | .Po 27 | cf.\& 28 | .Xr execline-block 7 29 | .Pc , 30 | .Ar gen... , 31 | and unquotes it. 32 | .Pp 33 | It runs 34 | .Ar gen... 35 | as a child process. 36 | .Ar gen Ap 37 | s output must not contain a null character. 38 | .Pp 39 | It reads 40 | .Ar gen Ap 41 | s output as it needs, splitting 42 | .Po 43 | cf.\& 44 | .Xr execline-transform 7 45 | .Pc 46 | it automatically. 47 | .Pp 48 | For every argument 49 | .Ar x 50 | in the split output, 51 | .Nm 52 | runs 53 | .Ar loop... 54 | as a child process, with 55 | .Sm off 56 | .Ar variable 57 | = 58 | .Ar x 59 | .Sm on 60 | added to its environment. 61 | .Pp 62 | .Nm 63 | then exits 0. 64 | .Pp 65 | You can start 66 | .Ar loop... 67 | with 68 | .Ql importas -u Ar variable Ar variable 69 | to perform variable substitution. 70 | .Nm 71 | is now implemented as a wrapper around the 72 | .Xr pipeline 1 73 | and 74 | .Xr forstdin 1 75 | commands, with calls to 76 | .Xr fdmove 1 77 | to ensure that 78 | .Ar loop... 79 | is called with the proper standard input. 80 | .Sh OPTIONS 81 | .Bl -tag -width x 82 | .It Fl p 83 | Parallel mode. 84 | Do not wait for a 85 | .Ar loop... 86 | instance to finish before spawning the next one. 87 | .Nm 88 | will still wait for all instances of 89 | .Ar loop 90 | to terminate before exiting, though. 91 | .It Fl o Ar okcodes 92 | .Ar okcodes 93 | must be a comma-separated list of exit codes. 94 | If the 95 | .Fl p 96 | flag hasn't been given and 97 | .Ar loop 98 | exits with one of the codes in 99 | .Ar okcodes , 100 | .Nm 101 | will run the following instances of the loop, but if the exit code is 102 | not listed in 103 | .Ar okcodes , 104 | .Nm 105 | will exit immediately with an approximation 106 | .Po 107 | cf.\& 108 | .Xr execline-exitcodes 7 109 | .Pc 110 | of the same exit code. 111 | .It Fl x Ar breakcodes 112 | Like the previous option, but with inverted meaning - the listed exit 113 | codes are codes that will make 114 | .Nm 115 | break the loop and exit, and the unlisted exit codes will make it keep 116 | looping. 117 | .It Fl e 118 | No autoimport. 119 | This is the default. 120 | .It Fl E 121 | Autoimport. 122 | Instead of spawning 123 | .Ar loop... , 124 | spawn 125 | .Ql importas -ui Ar variable Ar variable Ar loop... . 126 | This substitutes 127 | .Ar variable 128 | into the command line instead of putting it into the environment. 129 | .El 130 | .Pp 131 | Other options are similar (in name and functionality) to the switches 132 | passed to control a substitution mechanism[1] 133 | .Po 134 | cf.\& 135 | .Xr execline-transform 7 136 | .Pc , 137 | on purpose; however, 138 | .Nm 139 | does not call the substitution mechanism and has its own semantics for 140 | those options. 141 | .Bl -tag -width x 142 | .It Fl N 143 | Store the whole line in 144 | .Ar variable , 145 | including the terminating newline (or other delimiter). 146 | .It Fl n 147 | Chomp a terminating delimiter from the line from stdin before storing 148 | it into 149 | .Ar variable . 150 | This is the default. 151 | .It Fl C 152 | Crunch. 153 | If there is an empty line (i.e. that only contains a delimiter), do 154 | not call 155 | .Ar loop . 156 | If this option is given, 157 | .Em and 158 | chomping is active, 159 | .Em and 160 | the last line of stdin is not terminated by a delimiter, then this 161 | last line will not be processed. 162 | .It Fl c 163 | Do not crunch, call 164 | .Ar loop 165 | even if the line is empty. 166 | This is the default. 167 | .It Fl 0 168 | Accept null characters on its stdin, using them as delimiters. 169 | If this option and a 170 | .Fl d 171 | option are used simultaneously, the rightmost one wins. 172 | .It Fl d Ar delim 173 | Use the characters in string 174 | .Ar delim 175 | as delimiters for a line. 176 | Default is 177 | .Ql \en , 178 | meaning the input is only split on newlines. 179 | .El 180 | .Sh SEE ALSO 181 | .Xr execlineb 1 , 182 | .Xr fdmove 1 , 183 | .Xr forstdin 1 , 184 | .Xr forx 1 , 185 | .Xr loopwhilex 1 , 186 | .Xr pipeline 1 , 187 | .Xr execline-block 7 , 188 | .Xr execline-exitcodes 7 , 189 | .Xr execline-transform 7 190 | .Pp 191 | This man page is ported from the authoritative documentation at: 192 | .Lk https://skarnet.org/software/execline/forbacktickx.html 193 | .Sh AUTHORS 194 | .An Laurent Bercot 195 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 196 | -------------------------------------------------------------------------------- /man1/trap.1: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt TRAP 1 3 | .Os 4 | .Sh NAME 5 | .Nm trap 6 | .Nd trap signals and run a variety of commands according to the signals caught 7 | .Sh SYNOPSIS 8 | In an 9 | .Xr execlineb 1 10 | script: 11 | .Pp 12 | .Nm 13 | .Op Fl x 14 | .Bd -ragged -compact 15 | { 16 | .Ed 17 | .Bd -ragged -compact 18 | .Oo 19 | SIGTERM 20 | { 21 | .Ar progsigterm... 22 | } 23 | .Oc 24 | .Ed 25 | .Bd -ragged -compact 26 | .Oo 27 | quit 28 | { 29 | .Ar progsigquit 30 | \&... 31 | } 32 | .Oc 33 | .Ed 34 | .Bd -ragged -compact 35 | .Oo 36 | 1 37 | { 38 | .Ar progsighup 39 | \&... 40 | } 41 | .Oc 42 | .Ed 43 | .Bd -ragged -compact 44 | .Oo 45 | default 46 | { 47 | .Ar progdefault 48 | \&... 49 | } 50 | .Oc 51 | .Ed 52 | .Bd -ragged -compact 53 | \&... 54 | .Ed 55 | .Bd -ragged -compact 56 | } 57 | .Ed 58 | .Ar prog... 59 | .Sh DESCRIPTION 60 | .Nm 61 | reads a sequence of directives in a block 62 | .Po 63 | cf.\& 64 | .Xr execline-block 7 65 | .Pc . 66 | It expects at least one directive. 67 | .Pp 68 | Each directive is a keyword followed by a block. 69 | .Pp 70 | The keyword can be the special word 71 | .Ql timeout , 72 | a signal name (case-insensitive, with or without the 73 | .Ql SIG 74 | prefix), or a signal number. 75 | The block following it is a command line to run when the specified 76 | event occurs. 77 | .Pp 78 | .Nm 79 | sets traps for the various directives it reads. 80 | A trap for 81 | .Dv SIGTERM 82 | will be triggered when the 83 | .Nm 84 | program receives a 85 | .Dv SIGTERM . 86 | A 87 | .Ql default 88 | trap will be used for any signal that is not caught by another trap. 89 | .Pp 90 | It spawns a child executing 91 | .Ar prog... . 92 | .Pp 93 | It sets the 94 | .Ev \&! 95 | environment variable to the pid of the 96 | .Ar prog... 97 | process, and the 98 | .Ev SIGNAL 99 | environment variable to the trapped signal. 100 | .Pp 101 | Whenever it catches a signal, it spawns the program described in the 102 | corresponding directive. 103 | It will not spawn a program for the same signal twice: if the first 104 | subprocess is still active when another instance of the same signal 105 | arrives, this second instance is ignored. 106 | .Pp 107 | When 108 | .Ar prog... 109 | exits, 110 | .Nm 111 | exits with an approximation 112 | .Po 113 | cf.\& 114 | .Xr execline-exitcodes 7 115 | .Pc 116 | of the same exit code. 117 | .Pp 118 | Programs defined in command line directives can start with 119 | .Ql importas \&! \&! 120 | .Po 121 | cf.\& 122 | .Xr importas 1 123 | .Pc 124 | to retrieve the pid of 125 | .Ar prog 126 | in 127 | .Ql $! . 128 | If they need the signal number, which can be the case in 129 | .Ql default 130 | directives, they can for instance use 131 | .Ql multisubstitute { importas \&! \&! importas SIGNAL SIGNAL } 132 | .Po 133 | cf.\& 134 | .Xr multisubstitute 1 135 | .Pc 136 | to get both 137 | .Ql $! 138 | and 139 | .Ql $SIGNAL 140 | substitutions. 141 | .Pp 142 | The 143 | .Fl x 144 | option is basically a shortcut for a 145 | .Ql default { multisubstitute { importas \&! \&! importas SIGNAL SIGNAL } kill -$SIGNAL $! } 146 | directive. 147 | .Pp 148 | .Ql trap 149 | is a standard shell builtin, with similar functionality. 150 | It is more idiomatic, and probably more efficient, to use that builtin 151 | in shell scripts, and to only use the 152 | .Nm 153 | program in execline scripts. 154 | .Sh OPTIONS 155 | .Bl -tag -width x 156 | .It Fl x 157 | Forward signals. 158 | If this option is given, any signal that 159 | .Nm 160 | receives and that is not explicitly trapped will be sent to 161 | .Ar prog . 162 | By default, 163 | .Nm 164 | does not forward any signals, and does not ignore them either - for 165 | instance a 166 | .Dv SIGTERM , 167 | unless caught by a 168 | .Ql SIGTERM 169 | directive, will kill the 170 | .Nm 171 | process (and leave 172 | .Ar prog 173 | running). 174 | With the 175 | .Fl x 176 | option, without a 177 | .Ql SIGTERM 178 | directive, a 179 | .Dv SIGTERM 180 | will still be caught by 181 | .Nm , 182 | that will send it to 183 | .Ar prog . 184 | Note that if a 185 | .Ql default 186 | directive is present, this option does nothing. 187 | .El 188 | .Sh SEE ALSO 189 | .Xr emptyenv 1 , 190 | .Xr envfile 1 , 191 | .Xr exec 1 , 192 | .Xr execline-cd 1 , 193 | .Xr execline-umask 1 , 194 | .Xr execlineb 1 , 195 | .Xr exit 1 , 196 | .Xr export 1 , 197 | .Xr fdblock 1 , 198 | .Xr fdclose 1 , 199 | .Xr fdmove 1 , 200 | .Xr fdreserve 1 , 201 | .Xr fdswap 1 , 202 | .Xr getcwd 1 , 203 | .Xr getpid 1 , 204 | .Xr heredoc 1 , 205 | .Xr importas 1 , 206 | .Xr multisubstitute 1 , 207 | .Xr piperw 1 , 208 | .Xr posix-cd 1 , 209 | .Xr posix-umask 1 , 210 | .Xr redirfd 1 , 211 | .Xr tryexec 1 , 212 | .Xr unexport 1 , 213 | .Xr wait 1 , 214 | .Xr withstdinas 1 , 215 | .Xr execline-block 7 , 216 | .Xr execline-exitcodes 7 217 | .Pp 218 | This man page is ported from the authoritative documentation at: 219 | .Lk https://skarnet.org/software/execline/trap.html 220 | .Sh AUTHORS 221 | .An Laurent Bercot 222 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 223 | -------------------------------------------------------------------------------- /man7/execline-pushenv.7: -------------------------------------------------------------------------------- 1 | .Dd February 8, 2021 2 | .Dt EXECLINE-PUSHENV 7 3 | .Os 4 | .Sh NAME 5 | .Nm execline-pushenv 6 | .Nd pushing and popping the environment 7 | .Sh DESCRIPTION 8 | The 9 | .Xr execlineb 1 10 | launcher can store 11 | .Em positional parameters , 12 | i.e. arguments given to your script, into the environment. 13 | The 14 | .Ev \&# 15 | variable contains the number of arguments; the 16 | .Ev 0 17 | variable contains the name of your execline script; the 18 | .Ev 1 19 | variable contains the first argument; and so on. 20 | .Pp 21 | Up to execline-1.04, this could create problems with nested scripts: 22 | the inner script would overwrite the outer script's parameters, and 23 | there was no way to get them back. 24 | In particular, writing execline commands in the execline language via 25 | the 26 | .Xr runblock 1 27 | command was impossible. 28 | .Ss Push 29 | To solve that issue, execline now implements a kind of 30 | .Em environment stack . 31 | When 32 | .Xr execlineb 1 33 | reads the arguments, it does not overwrite the positional parameters, 34 | but 35 | .Em pushes 36 | them on a stack: 37 | .Bl -bullet -width x 38 | .It 39 | .Ev \&# 40 | will be set to the current number of arguments 41 | .It 42 | but if a variable named 43 | .Ev \&# 44 | existed before, it is renamed 45 | .Ev \&#:1 46 | .It 47 | and if a variable named 48 | .Ev \&#:1 49 | also existed, it is renamed 50 | .Ev \&#:2 51 | .It 52 | \&... and so on until 53 | .Ev \&# : Ns Ar n+1 54 | doesn't exist. 55 | .El 56 | .Pp 57 | Same goes for the other 58 | .Em positional parameters . 59 | .Pp 60 | The script then runs; and commands such as 61 | .Xr elgetpositionals 1 62 | use the current frame of positional parameters, without paying 63 | attention to the deeper levels. 64 | .Ss Pop 65 | When you are done with the arguments, it is advisable to 66 | .Em drop 67 | the current frame, and 68 | .Em pop 69 | the environment stack to get it back to its previous state: 70 | .Bl -bullet -width x 71 | .It 72 | .Ev \&# 73 | will be unset 74 | .It 75 | but if 76 | .Ev \&#:1 77 | exists, it will be renamed 78 | .Ev \&# 79 | .It 80 | and if 81 | .Ev \&#:2 82 | exists, it will be renamed 83 | .Ev \&#:1 84 | \&... and so on until 85 | .Ev \&# : Ns Ar n+1 86 | doesn't exist. 87 | .El 88 | .Pp 89 | Again, same goes for the other 90 | .Em positional parameters . 91 | The 92 | .Xr runblock 1 93 | command will perform that 94 | .Em pop 95 | operation automatically; the standard 96 | .Dq manual 97 | way to perform it is to use the 98 | .Ql emptyenv -P 99 | command. 100 | .Ss Substituting positional parameters without touching the environment 101 | Most of the time, you just need to substitute the positional 102 | parameters in your execline script, and don't need to go through the 103 | whole 104 | .Xr elgetpositionals 1 105 | and 106 | .Xr emptyenv 1 107 | chain. 108 | execline comes with an integrated substitution mechanism, that does 109 | not touch the environment at all: the 110 | .Ql -S Ar n 111 | option. 112 | .Pp 113 | Scripts beginning with: 114 | .Bd -literal -offset indent 115 | #!/command/execlineb -Sn 116 | foobar... 117 | .Ed 118 | .Pp 119 | are equivalent to: 120 | .Bd -literal -offset indent 121 | #!/command/execlineb 122 | elgetpositionals -Pn 123 | emptyenv -P 124 | foobar... 125 | .Ed 126 | .Pp 127 | So, to summarize, from most efficient (but less flexible) to least 128 | efficient (but more flexible): 129 | .Bl -bullet -width x 130 | .It 131 | Use 132 | .Ql execlineb -P 133 | if you don't need positional parameters at all; for instance, in s6[1] 134 | or runit[2] 135 | .Em run scripts . 136 | .It 137 | Use 138 | .Ql execlineb -S Ar n 139 | if you need only simple positional parameter substitution in your script - no 140 | .Xr shift 1 141 | or 142 | .Xr elgetopt 1 , 143 | no 144 | .Ql importas 1 1 . 145 | .It 146 | Use 147 | .Ql execlineb -p , 148 | then 149 | .Xr elgetpositionals 1 150 | if you don't mind overwriting the current stack of positional parameters. 151 | .It 152 | Use 153 | .Xr execlineb 1 , 154 | then 155 | .Xr elgetpositionals 1 , 156 | then 157 | .Ql emptyenv -P 158 | if you need the full power of positional parameter handling. 159 | .El 160 | .Sh EXAMPLES 161 | Suppose you want to run the long-lived program 162 | .Ar prog 163 | after printing the list of its arguments. 164 | .Bd -literal -offset indent 165 | #!/command/execlineb 166 | elgetpositionals 167 | foreground { echo $0 $@ } 168 | prog $@ 169 | .Ed 170 | .Pp 171 | will work, but will pollute 172 | .Ar prog Ap 173 | s environment with a set of positional parameters that have no meaning 174 | to it. 175 | A better script is: 176 | .Bd -literal -offset indent 177 | #!/command/execlineb 178 | elgetpositionals 179 | foreground { echo $0 $@ } 180 | emptyenv -P 181 | prog $@ 182 | .Ed 183 | .Pp 184 | which will run 185 | .Ar prog 186 | with the same environment as the script's caller. 187 | .Sh SEE ALSO 188 | .Xr elgetopt 1 , 189 | .Xr elgetpositionals 1 , 190 | .Xr emptyenv 1 , 191 | .Xr execlineb 1 , 192 | .Xr runblock 1 , 193 | .Xr shift 1 194 | .Pp 195 | [1] 196 | .Lk https://skarnet.org/software/s6/ 197 | .Pp 198 | [2] 199 | .Lk http://smarden.org/runit/ 200 | .Pp 201 | This man page is ported from the authoritative documentation at: 202 | .Lk https://skarnet.org/software/execline/el_pushenv.html 203 | .Sh AUTHORS 204 | .An Laurent Bercot 205 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 206 | -------------------------------------------------------------------------------- /man1/case.1: -------------------------------------------------------------------------------- 1 | .Dd March 13, 2022 2 | .Dt CASE 1 3 | .Os 4 | .Sh NAME 5 | .Nm case 6 | .Nd compare a value against a series of regular expressions, and execute into a program depending on the first expression the value 7 | matches 8 | .Sh SYNOPSIS 9 | In an 10 | .Xr execlineb 1 11 | script: 12 | .Pp 13 | .Nm 14 | .Op Fl S | s 15 | .Op Fl E | e 16 | .Op Fl i 17 | .Op Fl n | N 18 | .Ar value 19 | { 20 | .Bd -ragged -compact 21 | .Oo 22 | .Ar regex 23 | { 24 | .Ar prog... 25 | } 26 | .Oc 27 | .Ed 28 | .Bd -ragged -compact 29 | .Oo 30 | .Ar regex 31 | { 32 | .Ar prog... 33 | } 34 | .Oc 35 | .Ed 36 | .Ar ... 37 | .Bd -ragged -compact 38 | } 39 | .Ed 40 | .Bd -ragged -compact 41 | .Ar progdefault... 42 | .Ed 43 | .Sh DESCRIPTION 44 | .Nm 45 | reads an argument 46 | .Ar value 47 | and a sequence of directives in an 48 | .Xr execline-block 7 . 49 | .Pp 50 | Each directive is a regular expression followed by a block. 51 | .Pp 52 | .Nm 53 | matches 54 | .Ar value 55 | against the regular expressions in the order they are given. 56 | .Pp 57 | As soon as 58 | .Ar value 59 | matches a 60 | .Ar regex , 61 | .Nm case 62 | executes into the 63 | .Ar prog... 64 | command line that immediately follows the matched regex. 65 | .Pp 66 | If 67 | .Ar value 68 | matches no 69 | .Ar regex , 70 | .Nm 71 | eventually execs into 72 | .Ar progdefault... , 73 | or exits 0 if 74 | .Ar progdefault... 75 | is empty. 76 | .Pp 77 | .Ar value 78 | must match 79 | .Ar regex 80 | as a full word. 81 | If only a substring of 82 | .Ar value 83 | matches 84 | .Ar regex , 85 | it is not considered a match. 86 | .Pp 87 | If 88 | .Ar value 89 | matches no 90 | .Ar regex , 91 | .Ar progdefault... 92 | is always executed with an unmodified environment, whether 93 | subexpression matching has been requested or not. 94 | .Sh OPTIONS 95 | .Bl -tag -width e 96 | .It Fl s 97 | Shell matching. 98 | The 99 | .Ar regex 100 | words will not be interpreted as regular expressions, but as shell 101 | expressions to be interpreted via 102 | .Xr fnmatch 3 . 103 | The other options also change meanings, see the 104 | .Sx Shell matching 105 | section below. 106 | .It Fl S 107 | Regular expression matching. 108 | This is the default. 109 | This section, and all of the sections below except the 110 | .Sx Shell matching 111 | one, assumes that it is the case. 112 | .It Fl e 113 | Interpret the 114 | .Ar regex 115 | words as basic regular expressions[1]. 116 | .It Fl E 117 | Interpret the 118 | .Ar regex 119 | words as extended regular expressions[2]. 120 | This is the default. 121 | .It Fl i 122 | Perform case-insensitive matches. 123 | .It Fl N 124 | Make the matching expression and subexpressions available to 125 | .Ar prog Ap s 126 | environment. 127 | See the 128 | .Sx Subexpression matching 129 | section below. 130 | .It Fl n 131 | Do not transmit the matching expression and 132 | subexpressions to 133 | .Ar prog... 134 | via the environment. 135 | This is the default. 136 | .El 137 | .Ss Subexpression matching 138 | If the 139 | .Fl N 140 | option has been given, and 141 | .Ar value 142 | matches a 143 | .Ar regex , 144 | then 145 | .Nm 146 | will run 147 | .Ar prog 148 | with a modified environment: 149 | .Bl -bullet -width x 150 | .It 151 | The 152 | .Ev 0 153 | variable will contain the 154 | .Ar regex 155 | that 156 | .Ar value 157 | matched. 158 | .It 159 | The 160 | .Ev # 161 | variable will contain the number of subexpressions in 162 | .Ar regex . 163 | .It 164 | For every integer 165 | .Va i 166 | between 1 and the number of subexpressions (included), the variable 167 | .Va i 168 | contains the part of 169 | .Ar value 170 | that matched the 171 | .Va i Ns th 172 | in 173 | .Ar regex . 174 | .El 175 | .Pp 176 | To retrieve that information into your command line in an execline 177 | script, you can use the 178 | .Xr elgetpositionals 1 179 | program. 180 | .Ss Shell matching 181 | If the 182 | .Fl s 183 | option has been given to 184 | .Nm , 185 | then the 186 | .Ar regex 187 | words are not interpreted as regular expressions, but as shell 188 | patterns, as is performed by the shell's case conditional 189 | construct[3]. 190 | This has the following consequences: 191 | .Bl -bullet -width x 192 | .It 193 | Subexpression matching is always disabled. 194 | .It 195 | .Ar prog... 196 | is always executed with an unmodified environment. 197 | .It 198 | The options to the 199 | .Nm 200 | command change meanings: instead of controlling how the 201 | .Ar regex 202 | regular expressions are interpreted by the 203 | .Xr regcomp 3 204 | +primitive, they now control how 205 | .Ar value 206 | is matched against the 207 | .Ar regex 208 | patterns (which are not regular expressions!) via the 209 | .Xr fnmatch 3 210 | +primitive. 211 | Namely: 212 | .Bl -tag -width x 213 | .It Fl e 214 | Treat a backslash as an ordinary character; do not allow character 215 | escaping in patterns. 216 | .Po 217 | This sets the 218 | .Dv FNM_NOESCAPE 219 | flag. 220 | .Pc 221 | .It Fl E 222 | Allow backslash escaping in patterns. 223 | This is the default. 224 | .Po 225 | This clears the 226 | .Dv FNM_NOESCAPE 227 | flag. 228 | .Pc 229 | .It Fl i 230 | Treat a period 231 | .Po 232 | .Ql . 233 | .Pc 234 | as a special character for matching 235 | .Po 236 | set 237 | .Dv FNM_PERIOD 238 | .Pc . 239 | By default, the period is not a special character 240 | .Po 241 | .Dv FNM_PERIOD 242 | is cleared 243 | .Pc . 244 | .It Fl N 245 | Treat patterns as pathnames: make slashes character special. 246 | .Po 247 | This sets the 248 | .Dv FNM_PATHNAME 249 | flag. 250 | .Pc 251 | .It Fl n 252 | Do not treat patterns as pathnames 253 | .Po 254 | clear the 255 | .Dv FNM_PATHNAME 256 | flag 257 | .Pc . 258 | This is the default. 259 | .El 260 | .El 261 | .Sh EXAMPLES 262 | Consider the following script; say it's named 263 | .Ql match . 264 | .Bd -literal -offset indent 265 | #!/bin/execlineb -S1 266 | emptyenv 267 | case -N -- $1 268 | { 269 | "([fo]+)bar(baz)" { /usr/bin/env } 270 | } 271 | .Ed 272 | .Pp 273 | Running 274 | .Ql match foooobarbaz 275 | will print the following lines, corresponding to the output of the 276 | .Pa /usr/bin/env 277 | command: 278 | .Bd -literal -offset indent 279 | #=2 280 | 0=([fo]+)bar(baz) 281 | 1=foooo 282 | 2=baz 283 | .Ed 284 | .Sh SEE ALSO 285 | .Xr elgetpositionals 1 , 286 | .Xr execlineb 1 , 287 | .Xr execline-block 7 288 | .Pp 289 | [1] 290 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_03 291 | .Pp 292 | [2] 293 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html#tag_09_04 294 | .Pp 295 | [3] 296 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_09_04_05 297 | .Pp 298 | This man page is ported from the authoritative documentation at: 299 | .Lk https://skarnet.org/software/execline/case.html 300 | .Sh AUTHORS 301 | .An Laurent Bercot 302 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 303 | -------------------------------------------------------------------------------- /man1/eltest.1: -------------------------------------------------------------------------------- 1 | .Dd January 15, 2023 2 | .Dt ELTEST 1 3 | .Os 4 | .Sh NAME 5 | .Nm eltest 6 | .Nd evaluate an expression and indicate the result via its exit status 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Ar expression... 10 | .Sh DESCRIPTION 11 | .Nm 12 | acts as the generic POSIX 13 | .Pa test\& 14 | utility[1], but it diverges from the specification on how it parses 15 | ambiguous arguments, see below. 16 | .Pp 17 | .Nm 18 | supports all the standard 19 | .Pa test\& 20 | operands, plus all the extensions from GNU test[2], plus a few 21 | extensions from the 22 | .Ql test 23 | builtin from bash[3]. 24 | The extensions to POSIX 25 | .Pa test\& 26 | are listed below. 27 | .Pp 28 | .Nm 29 | accepts an arbitrary number of arguments and, if the expression is 30 | valid, always returns the result of the expression no matter how 31 | complex it is. 32 | .Ss Extensions 33 | .Bl -tag -width x 34 | .It Ar expr1 No -a Ar expr2 35 | Test whether 36 | .Ar expr1 37 | .Em and 38 | .Ar expr2 39 | are true. 40 | If 41 | .Ar expr1 42 | is false, then 43 | .Ar expr2 44 | is not evaluated. 45 | .It Ar expr1 No -o Ar expr2 46 | Test whether 47 | .Ar expr1 48 | .Em or 49 | .Ar expr2 50 | is true. 51 | If 52 | .Ar expr1 53 | is true, then 54 | .Ar expr2 55 | is not evaluated. 56 | .It No -k Ar file 57 | Test whether 58 | .Ar file 59 | has the sticky bit. 60 | .It No -O Ar file 61 | Test whether 62 | .Ar file 63 | is owned by the effective uid of the current process. 64 | .It No -U Ar file 65 | As for 66 | .Ql -O . 67 | .It No -G Ar file 68 | Test whether 69 | .Ar file Ap 70 | s gid is the effective gid of the current process. 71 | .It No -N Ar file 72 | Test whether 73 | .Ar file 74 | exists and has been modified since it was last read. 75 | .It Ar file1 No -nt Ar file2 76 | Test whether 77 | .Ar file1 78 | has a (strictly) newer modification date than 79 | .Ar file2 . 80 | .It Ar file1 No -ot Ar file2 81 | Test whether 82 | .Ar file1 83 | has a (strictly) older modification date than 84 | .Ar file2 . 85 | .It Ar file1 No -ef Ar file2 86 | Test whether 87 | .Ar file1 88 | and 89 | .Ar file2 90 | are physically the same file (same device and inode numbers). 91 | .It No -v Ar var 92 | Test whether the 93 | .Ar var 94 | variable is defined in the current environment. 95 | .It Ar string No =~ Ar pattern 96 | Tries to match 97 | .Ar string 98 | against extended regular expression 99 | .Ar pattern . 100 | True if any part of 101 | .Ar string 102 | matches 103 | .Ar pattern ; 104 | in order to match whole strings, you must anchor 105 | .Ar pattern 106 | with 107 | .Ql ^ 108 | and 109 | .Ql $ 110 | markers. 111 | .El 112 | .Ss Argument disambiguation 113 | Unlike 114 | .Pa test Ns 115 | [1], which has different fixed syntax trees depending on the number of 116 | arguments it receives and has undefined behaviour when called with 117 | more than 5 arguments, 118 | .Nm 119 | accepts any 120 | number of arguments and builds its syntax trees on the fly. 121 | This means that expressions such 122 | as 123 | .Ql -n = -n 124 | cannot be automatically disambiguated: 125 | .Nm 126 | does not know that 127 | there are 3 arguments, so when it reads the first 128 | .Ql -n 129 | it assumes that it is an unary operator, then when it reads 130 | .Ql = 131 | it assumes it is the argument to 132 | .Ql -n , 133 | then when it reads the second 134 | .Ql -n 135 | it exits with a syntax error. 136 | .Pp 137 | Doing otherwise would result in a combinatory explosion of possible 138 | syntax trees, making it easy for users to trigger unbounded RAM 139 | consumption, and turning a simple utility into a programming 140 | nightmare. 141 | This is why POSIX 142 | .Pa test Ns 143 | [1] is so restricted. 144 | But we don't want the same restrictions. 145 | .Pp 146 | So, instead, 147 | .Nm 148 | provides the user with a mechanism to make sure that operands are 149 | never mistaken for operators: 150 | .Bl -bullet -width x 151 | .It 152 | A word that looks like an operator will always be interpreted like an operator. 153 | So, expressions like 154 | .Ql -n = -n 155 | will result in a syntax error, because the first 156 | .Ql -n 157 | will never be understood as data for the 158 | .Ql = 159 | operator. 160 | .It 161 | A word that starts with a 162 | .Ql \e 163 | (backslash) will always be interpreted like data, never like an 164 | operator, and the backslash will be removed. 165 | This means 166 | .Ql \e-n = \e-n 167 | is a valid expression testing the equality between 168 | the strings 169 | .Ql -n 170 | and 171 | .Ql -n . 172 | .Bl -bullet -width x 173 | .It 174 | Be aware that execline as well as the shell use one backlash for their 175 | own unquoting mechanism, so when using backslashes in an execline or 176 | shell script, they must be doubled. 177 | You would probably need to type something like 178 | .Ql \e\e-n = \e\e-n . 179 | .El 180 | .It 181 | So, if your script tests equality between 182 | .Ql $a 183 | and 184 | .Ql $b , 185 | and there's a possiblity that the contents of these variables look like 186 | .Nm 187 | operators, the proper syntax would be: 188 | .Ql eltest \e\e${a} = \e\e${b} . 189 | .El 190 | .Pp 191 | Note that these details are irrelevant to a huge majority of 192 | .Nm 193 | use cases, because most of the time users only need a simple test 194 | such as 195 | .Ql eltest -r ${file} 196 | to check that 197 | .Ql $file 198 | is readable, and there's no possible ambiguity. 199 | So don't panic over this. 200 | .Ss Notes 201 | .Nm 202 | is a replacement for the ill-named, and now deprecated, 203 | .Xr s6-test 1 204 | program, part of the (just as ill-named) s6-portable-utils[4] package. 205 | It is too valuable a utility to be part of a marginal package, and has 206 | nothing to do with s6[5]. 207 | .Sh OPTIONS 208 | None. 209 | .Sh EXIT STATUS 210 | .Bl -tag -width x 211 | .It 0 212 | The test is true. 213 | .It 1 214 | The test is false. 215 | .It 100 216 | Wrong usage. 217 | .It 101 218 | Internal error (should never happen, warrants a bug-report). 219 | .It 111 220 | System call failure. 221 | .El 222 | .Sh SEE ALSO 223 | [1] 224 | .Lk https://pubs.opengroup.org/onlinepubs/9699919799/utilities/test.html 225 | .Pp 226 | [2] 227 | .Lk https://man7.org/linux/man-pages/man1/test.1.html 228 | .Pp 229 | [3] 230 | .Lk https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Bash-Conditional-Expressions 231 | .Pp 232 | [4] 233 | .Lk https://skarnet.org/software/s6-portable-utils/ 234 | .Pp 235 | [5] 236 | .Lk https://skarnet.org/software/s6/ 237 | .Pp 238 | This man page is ported from the authoritative documentation at: 239 | .Lk https://skarnet.org/software/execline/eltest.html 240 | .Sh STANDARDS 241 | .Nm 242 | .Em is not 243 | suitable as a Single Unix 244 | .Pa test Ns 245 | [1] program, due to the way it disambiguates between arguments and 246 | operators, as described in the 247 | .Sx Argument diambiguation 248 | section. 249 | However, if you never use arguments that start with a backslash, or 250 | that have the same name as an existing operator, then 251 | .Nm 252 | exhibits the same behaviour as 253 | .Pa test . 254 | .Sh AUTHORS 255 | .An Laurent Bercot 256 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 257 | -------------------------------------------------------------------------------- /man7/execline-grammar.7: -------------------------------------------------------------------------------- 1 | .Dd March 13, 2022 2 | .Dt EXECLINE-GRAMMAR 7 3 | .Os 4 | .Sh NAME 5 | .Nm execline-grammar 6 | .Nd the execline language design and grammar 7 | .Sh DESCRIPTION 8 | .Ss execline principles 9 | Here are some basic Unix facts: 10 | .Bl -bullet -width x 11 | .It 12 | Unix programs are started with the 13 | .Xr execve 2 14 | system call, which takes 3 arguments: the command name (which we won't 15 | discuss here because it's redundant in most cases), the command line 16 | .Ar argv , 17 | which specifies the program name and its arguments, and the environment 18 | .Ar envp . 19 | .It 20 | The 21 | .Ar argv 22 | structure makes it easy to read some arguments at the beginning of 23 | .Ar argv , 24 | perform some action, then 25 | .Xr execve 2 26 | into the rest of 27 | .Ar argv . 28 | For instance, the 29 | .Xr nice 1 30 | command works that way: 31 | .Ql nice -10 echo blah 32 | will read 33 | .Ql nice 34 | and 35 | .Ql -10 36 | from the 37 | .Ar argv , 38 | change the process' 39 | .Ar nice 40 | value, then 41 | .Xr exec 3 42 | into the command 43 | .Ql echo blah . 44 | This is called chain loading[1] by some people, and Bernstein 45 | chaining[2] by others. 46 | .It 47 | The purpose of the environment is to preserve some state across 48 | .Xr execve 2 49 | calls. 50 | This state is usually small: most programs keep their information in 51 | the filesystem. 52 | .It 53 | A 54 | .Em script 55 | is basically a text file whose meaning is a sequence of actions, 56 | i.e. calls to Unix programs, with some control over the execution 57 | flow. 58 | You need a program to interpret your script. 59 | Traditionally, this program is 60 | .Pa /bin/sh : 61 | scripts are written in the 62 | .Em shell 63 | language. 64 | .It 65 | The shell reads and interprets the script command after command. 66 | That means it must preserve a state, and stay in memory while the 67 | script is running. 68 | .It 69 | Standard shells have lots of built-in features and commands, so they 70 | are big. 71 | Spawning (i.e. 72 | .Xr fork 2 Ns 73 | ing then 74 | .Xr exec 3 Ns 75 | ing) a shell script takes time, because the shell program itself must 76 | be initialized. 77 | For simple programs like 78 | .Ql nice -10 echo blah , 79 | a shell is overpowered - we only need a way to make an 80 | .Ar argv 81 | from the 82 | .Dq nice -10 echo blah 83 | string, and 84 | .Xr execve 2 85 | into that 86 | .Ar argv . 87 | .It 88 | Unix systems have a size limit for 89 | .Sm off 90 | .Ar argv 91 | + 92 | .Ar envp , 93 | .Sm on 94 | but it is high. 95 | POSIX states that this limit must not be inferior to 4KB - and most 96 | simple scripts are smaller than that. 97 | Modern systems have a much higher limit: for instance, it is 64KB on 98 | .Fx 4.6 , 99 | and 128KB on Linux. 100 | .El 101 | .Pp 102 | Knowing that, and wanting lightweight and efficient scripts, I 103 | wondered: 104 | .Do 105 | Why should the interpreter stay in memory while the script is 106 | executing? 107 | Why not parse the script once and for all, put it all into one 108 | .Ar argv , 109 | and just execute into that 110 | .Ar argv , 111 | relying on external commands (which will be called from within the 112 | script) to control the execution flow? 113 | .Dc 114 | .Pp 115 | execline was born. 116 | .Pp 117 | execline is the first script language to rely 118 | .Em entirely 119 | on chain loading. 120 | An execline script is a single 121 | .Ar argv , 122 | made of a chain of programs designed to perform their action then 123 | .Xr exec 3 124 | into the next one. 125 | .Pp 126 | The 127 | .Xr execlineb 1 128 | command is a 129 | .Em launcher : 130 | it reads and parses a text file, converting it to an 131 | .Ar argv , 132 | then executes into that 133 | .Ar argv . 134 | It does nothing more. 135 | .Pp 136 | Straightforward scripts like 137 | .Ql nice -10 echo blah 138 | will be run just as they are, without the shell overhead. 139 | Here is what the script could look like: 140 | .Bd -literal -offset indent 141 | #!/command/execlineb -P 142 | nice -10 143 | echo blah 144 | .Ed 145 | .Pp 146 | More complex scripts will include calls to other execline commands, 147 | which are meant to provide some control over the process state and 148 | execution flow from inside an 149 | .Ar argv . 150 | .Ss Grammar of an execline script 151 | An execline script can be parsed as follows: 152 | .Bd -literal -offset indent 153 | = <> | 154 | external options | 155 | builtin options 156 | = <> | arg 157 | = <> | 158 | = { } | { } 159 | = <> | 160 | .Ed 161 | .Pp 162 | (This grammar is ambivalent, but much simpler to understand than the 163 | non-ambivalent ones.) 164 | .Pp 165 | An execline script is valid if it reduces to an 166 | .Em instruction . 167 | .Pp 168 | The empty 169 | .Em instruction 170 | is the same as the 171 | .Xr true 1 172 | command: when an execline component must exec into the empty 173 | instruction, it exits 0. 174 | .Pp 175 | Basically, every non-empty 176 | .Em instruction , 177 | be it 178 | .Do 179 | .Em builtin 180 | .Dc - 181 | an execline command - or 182 | .Do 183 | .Em external 184 | .Dc - 185 | a program such as 186 | .Xr echo 1 187 | or 188 | .Xr cp 1 - 189 | takes a number of arguments, the 190 | .Ar arglist , 191 | then executes into a (possibly empty) 192 | .Em instruction . 193 | .Pp 194 | Some 195 | .Em builtin Ns 196 | s are special because they also take a non-empty 197 | .Em blocklist 198 | after their 199 | .Ar arglist . 200 | For instance, 201 | the 202 | .Xr foreground 1 203 | command takes an empty 204 | .Ar arglist 205 | and one 206 | .Em block : 207 | .Bd -literal -offset indent 208 | #!/command/execlineb -P 209 | foreground { sleep 1 } echo blah 210 | .Ed 211 | .Pp 212 | is a valid 213 | .Xr execlineb 1 214 | script. 215 | The 216 | .Xr foreground 1 217 | command uses the 218 | .Ql sleep 1 219 | .Em block 220 | then 221 | .Xr exec 3 Ns 222 | s into the remaining 223 | .Ql echo blah 224 | .Em instruction . 225 | .Ss execline features 226 | execline commands can perform some transformations on their 227 | .Ar argv , 228 | to emulate some aspects of a shell. 229 | Here are descriptions of these features: 230 | .Bl -bullet -width x 231 | .It 232 | Block management 233 | .Po 234 | cf.\& 235 | .Xr execline-block 7 236 | .Pc . 237 | .It 238 | Variable substitution 239 | .Po 240 | cf.\& 241 | .Xr execline-substitute 7 242 | .Pc . 243 | .El 244 | .Sh SEE ALSO 245 | .Xr cp 1 , 246 | .Xr echo 1 , 247 | .Xr execlineb 1 , 248 | .Xr foreground 1 , 249 | .Xr nice 1 , 250 | .Xr true 1 , 251 | .Xr execve 2 , 252 | .Xr fork 2 , 253 | .Xr exec 3 , 254 | .Xr execline-block 7 , 255 | .Xr execline-substitute 7 256 | .Pp 257 | [1] 258 | .Lk https://en.wikipedia.org/wiki/Chain_loading 259 | .Pp 260 | [2] 261 | .Lk http://www.catb.org/~esr/writings/taoup/html/ch06s06.html 262 | .Pp 263 | This man page is ported from the authoritative documentation at: 264 | .Lk https://skarnet.org/software/execline/grammar.html 265 | .Sh AUTHORS 266 | .An Laurent Bercot 267 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 268 | -------------------------------------------------------------------------------- /man7/execline-transform.7: -------------------------------------------------------------------------------- 1 | .Dd March 24, 2022 2 | .Dt EXECLINE-TRANSFORM 7 3 | .Os 4 | .Sh NAME 5 | .Nm execline-transform 6 | .Nd overview of execline value transformation 7 | .Sh DESCRIPTION 8 | You can apply 3 kinds of transformations to a value which is to be 9 | substituted 10 | .Po 11 | cf.\& 12 | .Xr execline-substitute 7 13 | .Pc 14 | for a variable: crunching, chomping and splitting. 15 | They always occur in that order. 16 | .Ss Delimiters 17 | The transformations work around 18 | .Em delimiters . 19 | Delimiters are the semantic bounds of the 20 | .Dq words 21 | in your value. 22 | .Pp 23 | You can use any character (except the null character, which you cannot 24 | use in execline scripts) as a delimiter, by giving a string consisting 25 | of all the delimiters you want as the argument to the 26 | .Fl d 27 | option used by substitution commands. 28 | By default, the string 29 | .Ql \ \en\er\et 30 | is used, which means that the default delimiters are spaces, newlines, 31 | carriage returns and tabs. 32 | .Pp 33 | (The 34 | .Xr forstdin 1 35 | command is a small exception: by default, it only recognizes newlines 36 | as delimiters.) 37 | .Ss Crunching 38 | You can tell the substitution command to merge sets of consecutive 39 | delimiters into a single delimiter. 40 | For instance, to replace three consecutive spaces, or a space and 4 41 | tab characters, with a single space. 42 | This is called 43 | .Em crunching , 44 | and it is done by giving the 45 | .Fl C 46 | switch to the substitution command. 47 | The remaining delimiter will always be the first in the sequence. 48 | Crunching is 49 | .Em off 50 | by default, or if you give the 51 | .Fl c 52 | switch. 53 | .Pp 54 | Crunching is mainly useful when also 55 | .Sx Splitting . 56 | .Ss Chomping 57 | Sometimes you don't want the last delimiter in a value. 58 | .Em Chomping 59 | deletes the last character of a value if it is a delimiter. 60 | It is requested by giving the 61 | .Fl n 62 | switch to the substitution command. 63 | You can turn it off by giving the 64 | .Fl N 65 | switch. 66 | It is off by default unless mentioned in the documentation page of 67 | specific binaries. 68 | Note that chomping always happens 69 | .Em after 70 | crunching, which means you can use crunching+chomping to ignore, for 71 | instance, a set of trailing spaces. 72 | .Ss Splitting 73 | In a shell, when you write 74 | .Bd -literal -offset indent 75 | $ A='foo bar' ; echo $A 76 | .Ed 77 | .Pp 78 | the 79 | .Xr echo 1 80 | command is given two arguments, 81 | .Ql foo 82 | and 83 | .Ql bar . 84 | The 85 | .Ql $A 86 | value has been 87 | .Em split , 88 | and the space between 89 | .Ql foo 90 | and 91 | .Ql bar 92 | acted as a 93 | .Em delimiter . 94 | .Pp 95 | If you want to avoid splitting, you must write something like 96 | .Bd -literal -offset indent 97 | $ A='foo bar' ; echo "$A" 98 | .Ed 99 | .Pp 100 | The doublequotes 101 | .Dq protect 102 | the spaces. 103 | Unfortunately, it's easy to forget them and perform unwanted splits 104 | during script execution - countless bugs happen because of the shell's 105 | splitting behaviour. 106 | .Pp 107 | execline provides a 108 | .Em splitting 109 | facility, with several advantages over the shell's: 110 | .Bl -bullet -width x 111 | .It 112 | Splitting is off by default, which means that substitutions 113 | are performed as is, without interpreting the characters in the 114 | value. 115 | In execline, splitting has to be explicitly requested 116 | by specifying the 117 | .Fl s 118 | option to commands that perform substitution 119 | .Po 120 | cf.\& 121 | .Xr execline-substitute 7 122 | .Pc . 123 | .It 124 | Positional parameters are never split, so that execline scripts can 125 | handle arguments the way the user intended to. 126 | To split 127 | .Ql $1 , 128 | for instance, you have to ask for it specifically: 129 | .Bd -literal -offset indent 130 | #!/command/execlineb -S1 131 | define -sd" " ARG1S $1 132 | blah $ARG1S 133 | .Ed 134 | .Pp 135 | and 136 | .Ql $ARG1S 137 | will be split using the space character as only delimiter. 138 | .It 139 | Any character can be a delimiter. 140 | .El 141 | .Pp 142 | .Sy How it works 143 | .Bl -bullet -width x 144 | .It 145 | A substitution command can request that the substitution value be 146 | split, via the 147 | .Fl s 148 | switch. 149 | .It 150 | The splitting function parses the value, looking for delimiters. 151 | It fills up a structure, marking the split points, and the number 152 | .Ar n 153 | of words the value is to be split into. 154 | .Bl -bullet -width x 155 | .It 156 | A word is a sequence of characters in the value 157 | .Em terminated by a delimiter . 158 | The delimiter is not included in the word. 159 | .It 160 | If the value begins with 161 | .Ar x 162 | delimiters, the word list will begin with 163 | .Ar x 164 | empty words. 165 | .It 166 | The last sequence of characters in the value will be recognized as a 167 | word even if it is not terminated by a delimiter, unless you have 168 | requested 169 | .Sx Chomping 170 | and there was no delimiter at the end of the value 171 | .Em before 172 | the chomp operation - in which case that last sequence will not appear 173 | at all. 174 | .El 175 | .It 176 | The substitution rewrites the argv. 177 | A non-split value will be written as one word in the argv; a split 178 | value will be written as 179 | .Ar n 180 | separate words. 181 | .It 182 | Substitution of split values is performed recursively 183 | .Po 184 | cf.\& 185 | .Xr execline-substitute 7 186 | .Pc . 187 | .El 188 | .Pp 189 | .Sy Decoding netstrings 190 | .Pp 191 | Netstrings[1] are a way to reliably encode strings containing 192 | arbitrary characters. 193 | execline takes advantage of this to offer a completely safe splitting 194 | mechanism. 195 | If a substitution command is given an empty delimiter string (by use 196 | of the 197 | .Ql -d \(dq\(dq 198 | option), the splitting function will try to interpret the value as a 199 | sequence of netstrings, every netstring representing a word. 200 | For instance, in the following command line: 201 | .Bd -literal -offset indent 202 | $ define -s -d "" A '1:a,2:bb,0:,7:xyz 123,1: ,' echo '$A' 203 | .Ed 204 | .Pp 205 | the 206 | .Xr echo 1 207 | command will be given five arguments: 208 | .Bl -bullet -width x 209 | .It 210 | the 211 | .Ql a 212 | string 213 | .It 214 | the 215 | .Ql bb 216 | string 217 | .It 218 | the empty string 219 | .It 220 | the 221 | .Ql xyz 123 222 | string 223 | .It 224 | the 225 | .Ql \ \& 226 | string (a single space) 227 | .El 228 | .Pp 229 | However, if the value is not a valid sequence of netstrings, the 230 | substitution command will die with an error message. 231 | .Pp 232 | The 233 | .Xr dollarat 1 234 | command, for instance, can produce a sequence of netstrings (encoding 235 | all the arguments given to an execline script), meant to be decoded by 236 | a substitution command with the 237 | .Ql -d \(dq\(dq 238 | option. 239 | .Sh SEE ALSO 240 | .Xr dollarat 1 , 241 | .Xr echo 1 , 242 | .Xr forstdin 1 , 243 | .Xr execline-substitute 7 244 | .Pp 245 | [1] 246 | .Lk https://cr.yp.to/proto/netstrings.txt 247 | .Pp 248 | This man page is ported from the authoritative documentation at: 249 | .Lk https://skarnet.org/software/execline/el_transform.html 250 | .Sh AUTHORS 251 | .An Laurent Bercot 252 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 253 | -------------------------------------------------------------------------------- /man7/execline-substitute.7: -------------------------------------------------------------------------------- 1 | .Dd February 14, 2021 2 | .Dt EXECLINE-SUBSTITUTE 7 3 | .Os 4 | .Sh NAME 5 | .Nm execline-substitute 6 | .Nd overview of execline variable substitution 7 | .Sh DESCRIPTION 8 | In a shell, when you write 9 | .Bd -literal -offset indent 10 | $ A='foobar' ; echo $A 11 | .Ed 12 | .Pp 13 | the 14 | .Xr echo 1 15 | command is given the argument 16 | .Ql foobar . 17 | The 18 | .Ql foobar 19 | .Em value 20 | has been substituted for the 21 | .Ql A 22 | .Em variable . 23 | .Pp 24 | Although execline maintains no state, and thus has no real variables, 25 | it provides such a 26 | .Em substitution 27 | facility via 28 | .Em substitution commands , 29 | namely: 30 | .Bl -bullet -width x 31 | .It 32 | .Xr define 1 33 | .It 34 | .Xr importas 1 35 | .It 36 | .Xr elglob 1 37 | .It 38 | .Xr elgetpositionals 1 39 | .It 40 | .Xr multidefine 1 41 | .It 42 | .Xr multisubstitute 1 43 | .El 44 | .Pp 45 | A substitution command takes a 46 | .Em key , 47 | i.e. a string (which can contain any character but 48 | .Ql $ , 49 | .Ql { 50 | and 51 | .Ql } , 52 | although it is recommended to use only alphanumerical characters), and 53 | a way to compute a 54 | .Em value . 55 | .Ss Basics 56 | If the substitution key is 57 | .Ar foo , 58 | then the substitution command will look for every occurrence of 59 | .Ql ${ Ns Ar foo Ns } 60 | or 61 | .Ql $ Ns Ar foo 62 | in the rest of its argv. 63 | Note that 64 | .Ql ${ Ns Ar foo Ns }bar 65 | matches, but 66 | .Ql $ Ns Ar foo Ns bar 67 | .Sy does not . 68 | To be safe, always use the syntax with braces, unless 69 | .Ql $ Ns Ar foo 70 | is a word on its own. 71 | .Pp 72 | Every match is then replaced with the 73 | .Em value . 74 | .Pp 75 | The simplest example is the following: 76 | .Bd -literal -offset literal 77 | #!/command/execlineb 78 | define FOO blah 79 | echo $FOO 80 | .Ed 81 | .Pp 82 | which will replace the 83 | .Ql FOO 84 | key with the 85 | .Ql blah 86 | value, then execute the 87 | .Xr echo 1 88 | command. 89 | So that script will print 90 | .Ql blah 91 | on stdout. 92 | .Ss Quoting 93 | execline allows you to write literal 94 | .Ql ${ Ns Ar foo Ns } 95 | constructs even when the 96 | .Ar foo 97 | variable is being substituted, thanks to a quoting mechanism. 98 | Brace (pun intended) yourself: the following is the most complex part 99 | of the whole language. 100 | .Pp 101 | .Sy Rationale 102 | .Pp 103 | If we want to be able to have a literal ${foo}, then: 104 | .Bl -bullet -width x 105 | .It 106 | The 107 | .Ql ${ Ns Ar foo Ns } 108 | sequence will mean one of two things: be substituted, or 109 | .Em don't 110 | be substituted. 111 | .It 112 | The default (unquoted) action should be: substitute. 113 | .It 114 | A sequence that means 115 | .Dq do not substitute 116 | should be able to appear literally. 117 | The quote character should also be able to appear literally before a 118 | sequence that means 119 | .Dq substitute . 120 | (Tricky, eh?) 121 | .It 122 | There should be as few quote characters as possible, to avoid 123 | shell-like quoting nightmares. 124 | .El 125 | .Pp 126 | .Sy Syntax 127 | .Pp 128 | Rule: 129 | .Bl -bullet -width x 130 | .It 131 | The backslash 132 | .Po 133 | .Ql \e 134 | .Pc 135 | is a quote character for substitution commands. 136 | .It 137 | The following rule applies only if the 138 | .Ar foo 139 | key is explicitly used in a substitution command. 140 | If no command tries to substitute anything for 141 | .Ar foo , 142 | sequences like 143 | .Ql ${ Ns Ar foo Ns } 144 | and preceding backslashes are left untouched. 145 | .It 146 | (Substitute.) 147 | If 148 | .Ql ${ Ns Ar foo Ns } 149 | is preceded by 150 | .Ar 2*n 151 | backslashes 152 | (an 153 | .Sy even 154 | number), the whole sequence will be replaced with 155 | .Ar n 156 | backslashes, followed by the substituted value. 157 | .It 158 | (Do not substitute.) 159 | If 160 | .Ql ${ Ns Ar foo Ns } 161 | is preceded by 162 | .Ar 2*n+1 163 | backslashes 164 | (an 165 | .Sy odd 166 | number), the whole sequence will be replaced with 167 | .Ar n 168 | backslashes, followed by the literal 169 | .Ql ${ Ns Ar foo Ns } . 170 | .El 171 | .Pp 172 | And now, the catch: the 173 | .Xr execlineb 1 174 | launcher, as well as the shell, interprets backslashes as escape 175 | characters. 176 | To make a word that contains a backlash, you need to write 177 | .Em two 178 | backslashes in your execline script or shell command line. 179 | That means that the whole number of backslashes you must write before 180 | your 181 | .Ql ${ Ns Ar foo Ns } 182 | sequence must be doubled for the substitution command to read the 183 | proper number of backslashes and perform its work correctly. 184 | .Pp 185 | Once you keep that in mind, the quoting rule is logical. 186 | .Pp 187 | .Sy Example 188 | .Pp 189 | The quoting rule is best illustrated with the following example, where 190 | the 191 | .Ql A 192 | key is substituted, and the 193 | .Ql $B 194 | sequences mean nothing special. 195 | .Bd -literal -offset indent 196 | #!/command/execlineb 197 | define A val 198 | foreground { echo $A \e\e$A \e\e\e\e$A \e\e\e\e\e\e$A \e\e\e\e\e\e\e\e$A \e\e\e\e\e\e\e\e\e\e$A } 199 | echo $B \e\e$B \e\e\e\e$B \e\e\e\e\e\e$B \e\e\e\e\e\e\e\e$B \e\e\e\e\e\e\e\e\e\e$B 200 | .Ed 201 | .Pp 202 | prints 203 | .Bd -literal -offset indent 204 | val $A \eval \e$A \e\eval \e\e$A 205 | $B \e$B \e\e$B \e\e\e$B \e\e\e\e$B \e\e\e\e\e$B 206 | .Ed 207 | .Pp 208 | Phew. 209 | .Ss Value transformations 210 | A value can go through several transformations before it is 211 | substituted. 212 | It can be crunched, chomped, and/or split 213 | .Po 214 | cf.\& 215 | .Xr execline-transform 7 216 | .Pc 217 | .Ss Substitution of split values 218 | A 219 | .Ql split 220 | value for 221 | .Ql FOO 222 | means that a word containing 223 | .Ql ${FOO} 224 | will be replaced by zero, one, or (usually) more than one word. 225 | The value actually means a 226 | .Em list 227 | of values. 228 | .Pp 229 | The rule is: substituting a list of values 230 | .Po 231 | .Ar v1 , 232 | .Ar v2 , 233 | .Ar ... 234 | .Pc 235 | for a key 236 | .Ar A 237 | is the same as listing the substitutions of every value 238 | .Ar v Ns Ar i 239 | for 240 | .Ar A . 241 | .Pp 242 | For instance, 243 | .Bd -literal -offset indent 244 | #!/command/execlineb 245 | define -s FOO "v1 v2 v3" echo prefix-${FOO}-postfix 246 | .Ed 247 | .Pp 248 | will substitute three values for 249 | .Ql $FOO : 250 | .Ql v1 , 251 | .Ql v2 252 | and 253 | .Ql v3 . 254 | So the 255 | .Xr echo 1 256 | command will be called with three arguments: 257 | .Ql prefix-v1-postfix , 258 | .Ql prefix-v2-postfix , 259 | and 260 | .Ql prefix-v3-postfix . 261 | .Pp 262 | (Implementation note: the fact that word prefixes are kept is what 263 | makes execline's subtitutions secure. 264 | Blocks 265 | .Po 266 | cf.\& 267 | .Xr execline-block 7 268 | .Pc 269 | are implemented via prefix space characters; a substitution occurring 270 | inside a block will always produce words beginning with the right 271 | amount of spaces, thus substituted values cannot prematurely terminate 272 | a block.) 273 | .Pp 274 | .Sy Recursive substitutions 275 | .Pp 276 | A direct consequence of that rule is that substitutions will be 277 | performed recursively if more than one key appears in one word and the 278 | values for those keys are split. 279 | Parallel substitutions are performed from left to right. 280 | For instance, in 281 | .Bd -literal -offset indent 282 | #!/command/execlineb 283 | define -s B "1 2 3" echo ${B}x${B} 284 | .Ed 285 | .Pp 286 | the 287 | .Ql ${B}x${B} 288 | word will be replaced with 289 | .Em nine 290 | words: 291 | .Ql 1x1 , 292 | .Ql 1x2 , 293 | .Ql 1x3 , 294 | .Ql 2x1 , 295 | .Ql 2x2 , 296 | .Ql 2x3 , 297 | .Ql 3x1 , 298 | .Ql 3x2 , 299 | and 300 | .Ql 3x3 , 301 | in that order. 302 | .Pp 303 | Here is an example with two distinct substitutions in parallel: 304 | .Bd -literal -offset indent 305 | #!/command/execlineb 306 | multisubstitute 307 | { 308 | define -s A "a b c d" 309 | define -s B "1 2 3" 310 | } 311 | echo ${A}x${B} 312 | .Ed 313 | .Pp 314 | The 315 | .Ql ${A}x${B} 316 | word will be replaced with 317 | .Em twelve 318 | words: 319 | .Ql ax1 , 320 | .Ql ax2 , 321 | .Ql ax3 , 322 | .Ql bx1 , 323 | .Ql bx2 , 324 | .Ql bx3 , 325 | .Ql cx1 , 326 | .Ql cx2 , 327 | .Ql cx3 , 328 | .Ql dx1 , 329 | .Ql dx2 , 330 | and 331 | .Ql dx3 , 332 | in that order. 333 | You can check that the order of the 334 | .Ql define 335 | directives in 336 | .Xr multisubstitute 1 337 | does not matter. 338 | .Pp 339 | If the left-to-right order does not suit you, then you should perform 340 | .Em serial 341 | substitutions. 342 | For instance, the previous script can be replaced with 343 | .Bd -literal -offset indent 344 | #!/command/execlineb 345 | define -s B "1 2 3" 346 | define -s A "a b c d" 347 | echo ${A}x${B} 348 | .Ed 349 | .Pp 350 | and will substitute 351 | .Ql ${B} 352 | first, then 353 | .Ql ${A} . 354 | So it will print 355 | .Bd -literal -offset indent 356 | ax1 bx1 cx1 dx1 ax2 bx2 cx2 dx2 ax3 bx3 cx3 dx3 357 | .Ed 358 | .Pp 359 | in that order. 360 | .Ss Not for the faint of heart 361 | If you think you have mastered the art of execline substitution, then 362 | you can try to do better than these people: 363 | .Bl -bullet -width x 364 | .It 365 | Jo\(:el Riou[1] wrote the first execlineb quine[2], using 366 | only 367 | .Xr echo 1 368 | as non-execline external command. 369 | .It 370 | Shortly after, Paul Jarc[3] wrote a much shorter quine[4], using 371 | .Xr echo 1 372 | and 373 | .Xr env 1 374 | as non-execline external commands. 375 | He also wrote a revised version[5], using only 376 | .Xr echo 1 , 377 | and a shorter definitive version[6]. 378 | The last one is probably very close to the shortest possible execline 379 | quine. 380 | .It 381 | David Madore[7] wrote another quine[8], using 382 | .Xr printf 1 . 383 | His quine is longer than the other ones, but is well-commented and can 384 | be used as a tutorial on how to write quines. :) 385 | .El 386 | .Sh SEE ALSO 387 | .Xr define 1 , 388 | .Xr echo 1 , 389 | .Xr elgetpositionals 1 , 390 | .Xr elglob 1 , 391 | .Xr env 1 , 392 | .Xr execlineb 1 , 393 | .Xr importas 1 , 394 | .Xr multidefine 1 , 395 | .Xr multisubstitute 1 , 396 | .Xr multisubstitute 1 , 397 | .Xr printf 1 , 398 | .Xr execline-block 7 , 399 | .Xr execline-transform 7 400 | .Pp 401 | [1] 402 | .Lk http://jriou.org/ 403 | .Pp 404 | [2] 405 | .Lk https://skarnet.org/software/execline/quine-jriou.txt 406 | .Pp 407 | [3] 408 | .Lk https://code.dogmap.org/ 409 | .Pp 410 | [4] 411 | .Lk https://skarnet.org/software/execline/quine-prj.txt 412 | .Pp 413 | [5] 414 | .Lk https://skarnet.org/software/execline/quine-prj-2.txt 415 | .Pp 416 | [6] 417 | .Lk https://skarnet.org/software/execline/quine-prj-3.txt 418 | .Pp 419 | [7] 420 | .Lk http://www.madore.org/~david/ 421 | .Pp 422 | [8] 423 | .Lk https://skarnet.org/software/execline/quine-dam.txt 424 | .Pp 425 | This man page is ported from the authoritative documentation at: 426 | .Lk https://skarnet.org/software/execline/el_substitute.html 427 | .Sh AUTHORS 428 | .An Laurent Bercot 429 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 430 | -------------------------------------------------------------------------------- /man1/execlineb.1: -------------------------------------------------------------------------------- 1 | .Dd May 31, 2022 2 | .Dt EXECLINEB 1 3 | .Os 4 | .Sh NAME 5 | .Nm execlineb 6 | .Nd read and execute a script 7 | .Sh SYNOPSIS 8 | .Nm 9 | .Op Fl q | Fl w | Fl W 10 | .Op Fl p | Fl P | Fl S Ar nmin | Fl s Ar nmin 11 | .Fl c Ar script 12 | .Op Ar args... 13 | .Pp 14 | or 15 | .Pp 16 | .Nm 17 | .Op Fl q | Fl w | Fl W 18 | .Op Fl p | Fl P | Fl S Ar nmin | Fl s Ar nmin 19 | .Ar scriptfile 20 | .Op Ar args... 21 | .Pp 22 | or in an executable file: 23 | .\" Horrible kludge to get appropriate alignment. 24 | .Ss \& 25 | #!/command/execlineb 26 | .Op Fl qwWpPS Ns Ar nmin 27 | .Bd -ragged -compact 28 | .Ar script 29 | .Ed 30 | .\" End kludge. 31 | .Sh DESCRIPTION 32 | .Nm 33 | is a command launcher: it reads a file, turns that file into a command line, 34 | then executes into that command line. 35 | .Ss Parsing phase 36 | .Nm 37 | reads and parses the script it is given. 38 | It exits 100 on a syntax error and 111 on a temporary error. 39 | It makes an 40 | .Em argv , 41 | i.e. a system command line, with the parsed script. 42 | If the 43 | .Ar argv 44 | is empty, 45 | .Nm 46 | exits 0. 47 | .Ss Environment management phase 48 | .Bl -tag -width x 49 | .It Pushing the current stack frame 50 | If none of the 51 | .Fl p , 52 | .Fl P , 53 | .Fl S 54 | or 55 | .Fl s 56 | options are set: 57 | .Nm 58 | pushes 59 | .Po 60 | cf.\& 61 | .Xr execline-pushenv 7 62 | .Pc 63 | the current positional parameters, i.e. environment variables that 64 | start with 65 | .Ql # , 66 | .Ql 0 , 67 | .Ql 1 , 68 | \&... 69 | .Ql 9 . 70 | To get the previous values back, use 71 | .Ql emptyenv -P . 72 | .It Setting the new stack frame 73 | If none of the 74 | .Fl P , 75 | .Fl S 76 | or 77 | .Fl s 78 | options are set: 79 | .Bl -bullet -width x 80 | .It 81 | .Nm execlineb 82 | sets the 83 | .Ev \&# 84 | environment variable to the number 85 | .Ar n 86 | of 87 | .Ar args 88 | it is given. 89 | .It 90 | It sets the 91 | .Ev 0 92 | environment variable to the name of the script - or to the 93 | .Nm 94 | invocation name if the 95 | .Fl c 96 | option is used. 97 | .It 98 | It sets the 99 | .Ev 1 , 100 | .Ev 2 , 101 | \&... 102 | .Ar n 103 | environment variables to the different 104 | .Ar args . 105 | .El 106 | .El 107 | .Ss Execution phase 108 | .Nm 109 | executes into the 110 | .Ar argv 111 | it has built from the script. 112 | There is only one command line for the whole script: the 113 | .Nm 114 | binary is a 115 | .Em launcher , 116 | whose sole purpose is to execute into that command line. 117 | It does not stay in memory like a traditional 118 | .Em interpreter 119 | would. 120 | .Ss Syntax of scripts 121 | An 122 | .Nm 123 | script is a string that must not contain the null character. 124 | .Nm 125 | parses it and divides it into 126 | .Em words . 127 | .Pp 128 | The parser recognizes the following components: 129 | .Bl -bullet -width x 130 | .It 131 | .Em whitespace 132 | is defined as spaces, tabs, newlines and carriage returns. 133 | Words are always separated by whitespace. 134 | .It 135 | A 136 | .Em quoted string 137 | begins with a doublequote 138 | .Po 139 | .Ql \(dq 140 | .Pc 141 | and ends with another doublequote. 142 | Quoted doublequotes must be prefixed by a backslash 143 | .Po 144 | .Ql \e 145 | .Pc . 146 | Quoted strings always evaluate to exactly one word. 147 | For instance, 148 | .Ql \(dq\(dq 149 | evaluates to the empty word. 150 | .It 151 | The 152 | .Ql \ea , 153 | .Ql \eb , 154 | .Ql \et , 155 | .Ql \en , 156 | .Ql \ev , 157 | .Ql \ef , 158 | and 159 | .Ql \er 160 | sequences are recognized in quoted strings, and are converted to the 161 | ASCII numbers 7, 8, 9, 10, 11, 12 and 13 respectively. 162 | .It 163 | Inside a quoted string, backslashed newlines disappear completely. 164 | .It 165 | .Ql \e0x Ns Ar ab 166 | sequences are recognized in quoted strings and evaluate to ASCII 167 | hexadecimal number 168 | .Ar ab . 169 | .It 170 | .Ql \e0 Ns Ar abc 171 | sequences are recognized in quoted strings and evaluate to ASCII octal 172 | number 173 | .Ar abc . 174 | .Ar abc 175 | must not be greater than 377, or evaluate to 0. 176 | .It 177 | .Ql \e Ns Ar abc 178 | sequences are recognized in quoted strings and evaluate to ASCII 179 | decimal number 180 | .Ar abc . 181 | .Ar a 182 | must not be zero. 183 | .Ar abc 184 | must not be greater than 255, or evaluate to 0. 185 | .It 186 | A comment starts with a 187 | .Ql # 188 | and ends with the line. 189 | Comments 190 | are not recognized inside quoted strings. 191 | .It 192 | Anything else is an unquoted string, that can evaluate to zero or more 193 | words. 194 | .It 195 | Any character can be escaped in unquoted strings by prepending it with 196 | a backslash. 197 | It works the same way in quoted strings, except for the special 198 | sequences described above. 199 | .It 200 | As a special case, an unquoted backslash at the end of a line, or at 201 | the end of the input, is ignored. 202 | This is to make it easier to copy execline fragments from a shell 203 | script. 204 | .El 205 | .Pp 206 | You can see an example of distinct 207 | .Nm 208 | components in 209 | .Xr execline-components 7 . 210 | .Pp 211 | In addition to that simple lexing, 212 | .Nm 213 | performs the following higher-level parsing: 214 | .Bl -bullet -width x 215 | .It 216 | A word consisting of a single 217 | .Em opening brace 218 | .Po 219 | .Ql { 220 | .Pc 221 | increments an internal level counter, 222 | .Ar blevel , 223 | and disappears from the 224 | .Ar argv . 225 | Quoted open braces do not have that behaviour. 226 | .It 227 | A word consisting of a single 228 | .Em closing brace 229 | .Po 230 | .Ql } 231 | .Pc 232 | decrements 233 | .Ar blevel , 234 | and is replaced with the empty word. 235 | Quoted closing braces do not have that behaviour. 236 | .It 237 | If 238 | .Nm 239 | finds that braces are unmatched (i.e.\& 240 | .Ar blevel 241 | goes below 0 during the parsing, or is not 0 at the end of the 242 | script), it exits 100 with an error message. 243 | .It 244 | .Nm 245 | automatically quotes blocks 246 | .Po 247 | cf.\& 248 | .Xr execline-block 7 249 | .Pc . 250 | Which means that every time it finds a word, it prepends it with 251 | .Ar blevel 252 | spaces. 253 | .El 254 | .Pp 255 | For proper execution, the sequence of words must follow 256 | .Xr execline-grammar 7 . 257 | .Ss Current limitations 258 | .Nm 259 | builds and executes a unique 260 | .Ar argv 261 | with the script: hence scripts are subject to OS-dependent limitations 262 | such as the kernel buffer size for 263 | .Ar argv 264 | and 265 | .Ar envp 266 | - at least 64 kB on most systems. 267 | This means that 268 | .Nm 269 | cannot execute arbitrarily large scripts. 270 | Be careful with deeply nested scripts too: without the 271 | .Fl p 272 | / 273 | .Fl P 274 | / 275 | .Fl S 276 | / 277 | .Fl s 278 | option, each 279 | .Nm 280 | invocation uses up some space in the environment. 281 | .Sh OPTIONS 282 | .Bl -tag -width x 283 | .It Fl c Ar script 284 | Execute 285 | .Ar script , 286 | do not look for a file. 287 | .El 288 | .Pp 289 | See below for the other options. 290 | .Ss Options for block syntax checking 291 | External execline commands that read blocks, like 292 | .Xr foreground 1 , 293 | use the 294 | .Ev EXECLINE_STRICT 295 | environment variable: if it is set to 1, they will print a warning 296 | message on stderr if they find their blocks not to be properly quoted. 297 | If it is set to 2, they will also die. 298 | If it is set to 0, or unset, they won't complain at all. 299 | .Pp 300 | Normally the 301 | .Ev EXECLINE_STRICT 302 | environment variable is inherited from the caller. 303 | You can force it unset, set to 1, or set to 2 by giving respectively 304 | the 305 | .Fl q , 306 | .Fl w 307 | or 308 | .Fl W 309 | option to 310 | .Nm . 311 | .Pp 312 | The 313 | .Ev EXECLINE_STRICT 314 | variable (as well as the 315 | .Fl q , 316 | .Fl w 317 | and 318 | .Fl W 319 | options to 320 | .Nm Ns 321 | ) will also modify the behaviour of the 322 | .Fl S Ar nmin 323 | and 324 | .Fl s Ar nmin 325 | options when 326 | .Nm 327 | is called with less than 328 | .Ar nmin 329 | positional parameters: 330 | .Bl -bullet -width x 331 | .It 332 | If 333 | .Ev EXECLINE_STRICT 334 | is 0: the script will run silently, and missing positional parameters, 335 | up to 336 | .Ar nmin , 337 | will be substituted with the empty word. 338 | .It 339 | If 340 | .Ev EXECLINE_STRICT 341 | is 1 or unset: same, but the script will print a warning message 342 | rather than run silently. 343 | .It 344 | If 345 | .Ev EXECLINE_STRICT 346 | is 2: the script will exit with an error message. 347 | .El 348 | .Ss Options for environment management 349 | Normally, execline scripts are 350 | .Em reentrant : 351 | environment variables potentially overwritten by 352 | .Nm , 353 | such as 354 | .Ev \&# 355 | or 356 | .Ev 0 , 357 | are pushed 358 | .Po 359 | cf.\& 360 | .Xr execline-pushenv 7 361 | .Pc . 362 | This is the standard, safe behaviour. 363 | Nevertheless, it is rather costly, and may be unneeded for small 364 | scripts: for those cases, execline comes with two options that bypass 365 | the environment management. 366 | Be warned that the purpose of these options is 367 | .Sy optimization , 368 | and you should not use them if you're not familiar with the way 369 | .Nm 370 | uses the environment to store positional parameters. 371 | Alternatively, there's also an integrated substitution mechanism that 372 | doesn't make use of the environment at all. 373 | .Bl -bullet -width x 374 | .It 375 | The 376 | .Fl p 377 | option will bypass the push 378 | .Po 379 | cf.\& 380 | .Xr execline-pushenv 7 381 | .Pc 382 | phase: the current frame of positional parameters will be 383 | .Em overwritten . 384 | The script will 385 | .Em not 386 | be reentrant. 387 | .It 388 | The 389 | .Fl P 390 | option will bypass positional parameter handling 391 | .Em completely : 392 | the environment will not be pushed, and positional parameters will be 393 | ignored. 394 | .Ql execlineb -P -c \(dq Ns Ar script Ns \(dq 395 | is equivalent to, but more efficient than, 396 | .Ql execlineb -c \(dqemptyenv -P Ar script Ns \(dq 397 | .Pp 398 | You should use the 399 | .Fl P 400 | option only in standalone scripts that take no arguments, such as 401 | s6's[1] or runit's[2] 402 | .Em run scripts . 403 | .It 404 | The 405 | .Fl S Ar nmin 406 | option 407 | .Em will 408 | substitute the positional parameters - up to at least 409 | .Ar nmin 410 | - but 411 | .Em will not 412 | push nor set environment variables. 413 | .Ql execlineb -S3 -c \(dq Ns Ar script Ns \(dq 414 | is equivalent to, but more efficient than, 415 | .Ql execlineb -c \(dqelgetpositionals -P3 emptyenv -P Ar script Ns \(dq 416 | .Pp 417 | See 418 | .Xr execline-pushenv 7 419 | for details. 420 | .It 421 | The 422 | .Fl s Ar nmin 423 | option behaves just like the 424 | .Fl S 425 | option, except that it defines 426 | .Ql $@ 427 | as the rest of the command line 428 | .Sy after 429 | .Ar nmin 430 | arguments have been removed. 431 | .El 432 | .Sh SEE ALSO 433 | .Xr foreground 1 , 434 | .Xr execline-pushenv 7 435 | .Pp 436 | [1] 437 | .Lk https://skarnet.org/software/s6/ 438 | .Pp 439 | [2] 440 | .Lk http://smarden.org/runit/ 441 | .Pp 442 | This man page is ported from the authoritative documentation at: 443 | .Lk https://skarnet.org/software/execline/execlineb.html 444 | .Sh AUTHORS 445 | .An Laurent Bercot 446 | .An Alexis Ao Mt flexibeast@gmail.com Ac (man page port) 447 | --------------------------------------------------------------------------------