texi-files generated from pod2texi.

configure

@@ -1,6 +1,6 @@
 #! /bin/sh
 # Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.68 for parallel 20120122.
+# Generated by GNU Autoconf 2.68 for parallel 20120124.
 #
 # Report bugs to <bug-parallel@gnu.org>.
 #
@@ -559,8 +559,8 @@ MAKEFLAGS=
 # Identity of this package.
 PACKAGE_NAME='parallel'
 PACKAGE_TARNAME='parallel'
-PACKAGE_VERSION='20120122'
+PACKAGE_VERSION='20120124'
-PACKAGE_STRING='parallel 20120122'
+PACKAGE_STRING='parallel 20120124'
 PACKAGE_BUGREPORT='bug-parallel@gnu.org'
 PACKAGE_URL=''
 
@@ -1176,7 +1176,7 @@ if test "$ac_init_help" = "long"; then
   # Omit some internal or obsolete options to make the list less imposing.
   # This message is too long to be a string in the A/UX 3.1 sh.
   cat <<_ACEOF
-\`configure' configures parallel 20120122 to adapt to many kinds of systems.
+\`configure' configures parallel 20120124 to adapt to many kinds of systems.
 
 Usage: $0 [OPTION]... [VAR=VALUE]...
 
@@ -1242,7 +1242,7 @@ fi
 
 if test -n "$ac_init_help"; then
   case $ac_init_help in
-     short | recursive ) echo "Configuration of parallel 20120122:";;
+     short | recursive ) echo "Configuration of parallel 20120124:";;
    esac
   cat <<\_ACEOF
 
@@ -1309,7 +1309,7 @@ fi
 test -n "$ac_init_help" && exit $ac_status
 if $ac_init_version; then
   cat <<\_ACEOF
-parallel configure 20120122
+parallel configure 20120124
 generated by GNU Autoconf 2.68
 
 Copyright (C) 2010 Free Software Foundation, Inc.
@@ -1326,7 +1326,7 @@ cat >config.log <<_ACEOF
 This file contains any messages produced by compilers while
 running configure, to aid debugging if configure makes a mistake.
 
-It was created by parallel $as_me 20120122, which was
+It was created by parallel $as_me 20120124, which was
 generated by GNU Autoconf 2.68.  Invocation command line was
 
   $ $0 $@
@@ -2141,7 +2141,7 @@ fi
 
 # Define the identity of the package.
  PACKAGE='parallel'
- VERSION='20120122'
+ VERSION='20120124'
 
 
 cat >>confdefs.h <<_ACEOF
@@ -2704,7 +2704,7 @@ cat >>$CONFIG_STATUS <<\_ACEOF || ac_write_fail=1
 # report actual input values of CONFIG_FILES etc. instead of their
 # values after options handling.
 ac_log="
-This file was extended by parallel $as_me 20120122, which was
+This file was extended by parallel $as_me 20120124, which was
 generated by GNU Autoconf 2.68.  Invocation command line was
 
   CONFIG_FILES    = $CONFIG_FILES
@@ -2766,7 +2766,7 @@ _ACEOF
 cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
 ac_cs_version="\\
-parallel config.status 20120122
+parallel config.status 20120124
 configured by $0, generated by GNU Autoconf 2.68,
   with options \\"\$ac_cs_config\\"
 

configure.ac

@@ -1,4 +1,4 @@
-AC_INIT([parallel], [20120122], [bug-parallel@gnu.org])
+AC_INIT([parallel], [20120124], [bug-parallel@gnu.org])
 AM_INIT_AUTOMAKE([-Wall -Werror foreign])
 AC_CONFIG_HEADERS([config.h])
 AC_CONFIG_FILES([

doc/FUTURE_IDEAS

@@ -131,7 +131,7 @@ Husk at skrive indholdet under billedet, det er irreterende at skulle gætte.
 GNU parallel is a UNIX-tool for running commands in parallel.
 To gzip all files running one job per CPU write:
   parallel gzip ::: *
-Watch the intro video to learn more: http://nd.gd/0s
+Watch the intro video to learn more: www.pi.dk/1
 Or read more about GNU parallel: www.gnu.org/s/parallel
 
 job->start():

doc/release_new_version

@@ -142,7 +142,8 @@ http://freshmeat.net/projects/parallel/releases/new
 New version of #GNU Parallel http://pi.dk/0 released. See what is new
 in this release http://pi.dk/2 Watch the intro videos http://pi.dk/1
 
-https://savannah.gnu.org/news/?group=parallel
+[x] Twitter
+Aspect: Public
 
 == Send announce ==
 

src/Makefile.am

@@ -1,6 +1,6 @@
 bin_SCRIPTS = parallel sem sql niceload
 man_MANS = parallel.1 sem.1 sql.1 niceload.1
-doc_DATA = parallel.html sem.html sql.html niceload.html
+doc_DATA = parallel.html sem.html sql.html niceload.html parallel.texi sem.texi sql.texi niceload.texi
 
 parallel.1: parallel.pod Makefile
 	pod2man --release='$(PACKAGE_VERSION)' --center='$(PACKAGE_NAME)' \
@@ -22,19 +22,33 @@ parallel.html: parallel.pod Makefile
 	pod2html $(srcdir)/parallel.pod > $(srcdir)/parallel.html
 	rm -f $(srcdir)/pod2htm*
 
-# Depending on parallel.html to avoid pod2html race condition
+# Depending on parallel.html to avoid stupid pod2html race condition
 sem.html: sem.pod Makefile parallel.html
 	pod2html $(srcdir)/sem.pod > $(srcdir)/sem.html
 	rm -f $(srcdir)/pod2htm*
 
+# Depending on sem.html to avoid stupid pod2html race condition
 sql.html: sql Makefile sem.html
 	pod2html $(srcdir)/sql > $(srcdir)/sql.html
 	rm -f $(srcdir)/pod2htm*
 
+# Depending on sql.html to avoid stupid pod2html race condition
 niceload.html: niceload.pod Makefile sql.html
 	pod2html $(srcdir)/niceload.pod > $(srcdir)/niceload.html
 	rm -f $(srcdir)/pod2htm*
 
+parallel.texi: parallel.pod
+	pod2texi --output=$(srcdir)/parallel.texi $(srcdir)/parallel.pod
+
+sem.texi: sem.pod
+	pod2texi --output=$(srcdir)/sem.texi $(srcdir)/sem.pod
+
+sql.texi: sql
+	pod2texi --output=$(srcdir)/sql.texi $(srcdir)/sql
+
+niceload.texi: niceload.pod
+	pod2texi --output=$(srcdir)/niceload.texi $(srcdir)/niceload.pod
+
 sem: parallel
 	ln -fs parallel sem
 

src/Makefile.in

@@ -148,7 +148,7 @@ top_builddir = @top_builddir@
 top_srcdir = @top_srcdir@
 bin_SCRIPTS = parallel sem sql niceload
 man_MANS = parallel.1 sem.1 sql.1 niceload.1
-doc_DATA = parallel.html sem.html sql.html niceload.html
+doc_DATA = parallel.html sem.html sql.html niceload.html parallel.texi sem.texi sql.texi niceload.texi
 DISTCLEANFILES = parallel.html sem.html sql.html niceload.html
 EXTRA_DIST = parallel sem sql niceload \
 	parallel.1 sem.1 sql.1 niceload.1 \
@@ -467,19 +467,33 @@ parallel.html: parallel.pod Makefile
 	pod2html $(srcdir)/parallel.pod > $(srcdir)/parallel.html
 	rm -f $(srcdir)/pod2htm*
 
-# Depending on parallel.html to avoid pod2html race condition
+# Depending on parallel.html to avoid stupid pod2html race condition
 sem.html: sem.pod Makefile parallel.html
 	pod2html $(srcdir)/sem.pod > $(srcdir)/sem.html
 	rm -f $(srcdir)/pod2htm*
 
+# Depending on sem.html to avoid stupid pod2html race condition
 sql.html: sql Makefile sem.html
 	pod2html $(srcdir)/sql > $(srcdir)/sql.html
 	rm -f $(srcdir)/pod2htm*
 
+# Depending on sql.html to avoid stupid pod2html race condition
 niceload.html: niceload.pod Makefile sql.html
 	pod2html $(srcdir)/niceload.pod > $(srcdir)/niceload.html
 	rm -f $(srcdir)/pod2htm*
 
+parallel.texi: parallel.pod
+	pod2texi --output=$(srcdir)/parallel.texi $(srcdir)/parallel.pod
+
+sem.texi: sem.pod
+	pod2texi --output=$(srcdir)/sem.texi $(srcdir)/sem.pod
+
+sql.texi: sql
+	pod2texi --output=$(srcdir)/sql.texi $(srcdir)/sql
+
+niceload.texi: niceload.pod
+	pod2texi --output=$(srcdir)/niceload.texi $(srcdir)/niceload.pod
+
 sem: parallel
 	ln -fs parallel sem
 

src/niceload

@@ -24,7 +24,7 @@
 use strict;
 use Getopt::Long;
 $Global::progname="niceload";
-$Global::version = 20120122;
+$Global::version = 20120124;
 Getopt::Long::Configure("bundling","require_order");
 get_options_from_array(\@ARGV) || die_usage();
 if($::opt_version) {

src/niceload.texi

@@ -0,0 +1,409 @@
+\input texinfo
+@setfilename niceload.info
+
+@documentencoding utf-8
+
+@settitle niceload - slow down a program when the load average is above a certain limit
+
+@node Top
+@top niceload
+
+@chapter NAME
+@anchor{NAME}
+
+niceload - slow down a program when the load average is above a certain limit
+
+@chapter SYNOPSIS
+@anchor{SYNOPSIS}
+
+@strong{niceload} [-v] [-h] [-n nice] [-I io] [-L load] [-M mem] [-N]
+[-t time] [-s time|-f factor] ( command | -p PID )
+
+@chapter DESCRIPTION
+@anchor{DESCRIPTION}
+
+GNU @strong{niceload} will slow down a program when the load average (or
+other system activity) is above a certain limit. When the limit is
+reached the program will be suspended for some time. Then resumed
+again for some time.  Then the load average is checked again and we
+start over.
+
+Instead of load average @strong{niceload} can also look at disk I/O, amount
+of free memory, or swapping activity.
+
+If the load is 3.00 then the default settings will run a program
+like this:
+
+run 1 second, suspend (3.00-1.00) seconds, run 1 second, suspend
+(3.00-1.00) seconds, run 1 second, ...
+
+@chapter OPTIONS
+@anchor{OPTIONS}
+
+@table @asis
+@item @strong{-f} @emph{FACTOR}
+@anchor{@strong{-f} @emph{FACTOR}}
+
+@item @strong{--factor} @emph{FACTOR}
+@anchor{@strong{--factor} @emph{FACTOR}}
+
+Suspend time factor. Dynamically set @strong{-s} as amount over limit *
+factor. Default is 1.
+
+@item @strong{-H}
+@anchor{@strong{-H}}
+
+@item @strong{--hard}
+@anchor{@strong{--hard}}
+
+Hard limit. @strong{--hard} will suspend the process until the system is
+under the limits. The default is @strong{--soft}.
+
+@item @strong{--io} @emph{iolimit}
+@anchor{@strong{--io} @emph{iolimit}}
+
+@item @strong{-I} @emph{iolimit}
+@anchor{@strong{-I} @emph{iolimit}}
+
+Limit for I/O. The amount of disk I/O will be computed as a value 0 -
+10, where 0 is no I/O and 10 is at least one disk is 100% satuated.
+
+@strong{--io} will set both @strong{--start-io} and @strong{run-io}.
+
+@item @strong{--load} @emph{loadlimit}
+@anchor{@strong{--load} @emph{loadlimit}}
+
+@item @strong{-L} @emph{loadlimit}
+@anchor{@strong{-L} @emph{loadlimit}}
+
+Limit for load average.
+
+@strong{--load} will set both @strong{--start-load} and @strong{run-load}.
+
+@item @strong{--mem} @emph{memlimit}
+@anchor{@strong{--mem} @emph{memlimit}}
+
+@item @strong{-M} @emph{memlimit}
+@anchor{@strong{-M} @emph{memlimit}}
+
+Limit for free memory. This is the amount of bytes available as free
++ cache. This limit is treated opposite other limits: If the system
+is above the limit the program will run, if it is below the limit the
+program will stop
+
+@emph{memlimit} can be postfixed with K, M, G, T, or P which would
+multiply the size with 1024, 1048576, 1073741824, or 1099511627776
+respectively.
+
+@strong{--mem} will set both @strong{--start-mem} and @strong{run-mem}.
+
+@item @strong{--noswap}
+@anchor{@strong{--noswap}}
+
+@item @strong{-N}
+@anchor{@strong{-N}}
+
+No swapping. If the system is swapping both in and out it is a good
+indication that the system is memory stressed.
+
+@strong{--noswap} is over limit if the system is swapping both in and out.
+
+@strong{--noswap} will set both @strong{--start-noswap} and @strong{run-noswap}.
+
+@item @strong{-n} @emph{niceness}
+@anchor{@strong{-n} @emph{niceness}}
+
+@item @strong{--nice} @emph{niceness}
+@anchor{@strong{--nice} @emph{niceness}}
+
+Sets niceness. See @strong{nice}(1).
+
+@item @strong{-p} @emph{PID}
+@anchor{@strong{-p} @emph{PID}}
+
+@item @strong{--pid} @emph{PID}
+@anchor{@strong{--pid} @emph{PID}}
+
+Process ID of process to suspend.
+
+@item @strong{--quote}
+@anchor{@strong{--quote}}
+
+@item @strong{-q}
+@anchor{@strong{-q}}
+
+Quote the command line. Useful if the command contains chars like *,
+$, >, and " that should not be interpreted by the shell.
+
+@item @strong{--run-io} @emph{iolimit}
+@anchor{@strong{--run-io} @emph{iolimit}}
+
+@item @strong{--ri} @emph{iolimit}
+@anchor{@strong{--ri} @emph{iolimit}}
+
+@item @strong{--run-load} @emph{loadlimit}
+@anchor{@strong{--run-load} @emph{loadlimit}}
+
+@item @strong{--rl} @emph{loadlimit}
+@anchor{@strong{--rl} @emph{loadlimit}}
+
+@item @strong{--run-mem} @emph{memlimit}
+@anchor{@strong{--run-mem} @emph{memlimit}}
+
+@item @strong{--rm} @emph{memlimit}
+@anchor{@strong{--rm} @emph{memlimit}}
+
+Run limit. The running program will be slowed down if the system is
+above the limit. See: @strong{--io}, @strong{--load}, @strong{--mem}, @strong{--noswap}.
+
+@item @strong{--start-io} @emph{iolimit}
+@anchor{@strong{--start-io} @emph{iolimit}}
+
+@item @strong{--si} @emph{iolimit}
+@anchor{@strong{--si} @emph{iolimit}}
+
+@item @strong{--start-load} @emph{loadlimit}
+@anchor{@strong{--start-load} @emph{loadlimit}}
+
+@item @strong{--sl} @emph{loadlimit}
+@anchor{@strong{--sl} @emph{loadlimit}}
+
+@item @strong{--start-mem} @emph{memlimit}
+@anchor{@strong{--start-mem} @emph{memlimit}}
+
+@item @strong{--sm} @emph{memlimit}
+@anchor{@strong{--sm} @emph{memlimit}}
+
+Start limit. The program will not start until the system is below the
+limit. See: @strong{--io}, @strong{--load}, @strong{--mem}, @strong{--noswap}.
+
+@item @strong{--soft}
+@anchor{@strong{--soft}}
+
+@item @strong{-S}
+@anchor{@strong{-S}}
+
+Soft limit. @strong{niceload} will suspend a process for a while and then
+let it run for a second thus only slowing down a process while the
+system is over one of the given limits. This is the default.
+
+@item @strong{--suspend} @emph{SEC}
+@anchor{@strong{--suspend} @emph{SEC}}
+
+@item @strong{-s} @emph{SEC}
+@anchor{@strong{-s} @emph{SEC}}
+
+Suspend time. Suspend the command this many seconds when the max load
+average is reached.
+
+@item @strong{--recheck} @emph{SEC}
+@anchor{@strong{--recheck} @emph{SEC}}
+
+@item @strong{-t} @emph{SEC}
+@anchor{@strong{-t} @emph{SEC}}
+
+Recheck load time. Sleep SEC seconds before checking load
+again. Default is 1 second.
+
+@item @strong{--verbose}
+@anchor{@strong{--verbose}}
+
+@item @strong{-v}
+@anchor{@strong{-v}}
+
+Verbose. Print some extra output on what is happening. Use @strong{-v} until
+you know what your are doing.
+
+@end table
+
+@chapter EXAMPLE: See niceload in action
+@anchor{EXAMPLE: See niceload in action}
+
+In terminal 1 run: top
+
+In terminal 2 run:
+
+@strong{niceload perl -e '$|=1;do@{$l==$r or print "."; $l=$r@}until(($r=time-$^T)}>@strong{50)'}
+
+This will print a '.' every second for 50 seconds and eat a lot of
+CPU. When the load rises to 1.0 the process is suspended.
+
+@chapter EXAMPLE: Run updatedb
+@anchor{EXAMPLE: Run updatedb}
+
+Running updatedb can often starve the system for disk I/O and thus result in a high load.
+
+Run updatedb but suspend updatedb if the load is above 2.00:
+
+@strong{niceload -L 2 updatedb}
+
+@chapter EXAMPLE: Run rsync
+@anchor{EXAMPLE: Run rsync}
+
+rsync can just like updatedb starve the system for disk I/O and thus result in a high load.
+
+Run rsync but keep load below 3.4. If load reaches 7 sleep for
+(7-3.4)*12 seconds:
+
+@strong{niceload -L 3.4 -f 12 rsync -Ha /home/ /backup/home/}
+
+@chapter EXAMPLE: Ensure enough disk cache
+@anchor{EXAMPLE: Ensure enough disk cache}
+
+Assume the program @strong{foo} uses 2 GB files intensively. @strong{foo} will run
+fast if the files are in disk cache and be slow as a crawl if they are
+not in the cache.
+
+To ensure 2 GB are reserved for disk cache run:
+
+@strong{niceload --hard --run-mem 2g foo}
+
+This will not guarantee that the 2 GB memory will be used for the
+files for @strong{foo}, but it will stop @strong{foo} if the memory for disk cache
+is too low.
+
+@chapter ENVIRONMENT VARIABLES
+@anchor{ENVIRONMENT VARIABLES}
+
+None. In future versions $NICELOAD will be able to contain default settings.
+
+@chapter EXIT STATUS
+@anchor{EXIT STATUS}
+
+Exit status should be the same as the command being run (untested).
+
+@chapter REPORTING BUGS
+@anchor{REPORTING BUGS}
+
+Report bugs to <bug-parallel@@gnu.org>.
+
+@chapter AUTHOR
+@anchor{AUTHOR}
+
+Copyright (C) 2004-11-19 Ole Tange, http://ole.tange.dk
+
+Copyright (C) 2005,2006,2006,2008,2009,2010 Ole Tange, http://ole.tange.dk
+
+Copyright (C) 2010,2011 Ole Tange, http://ole.tange.dk and Free
+Software Foundation, Inc.
+
+@chapter LICENSE
+@anchor{LICENSE}
+
+Copyright (C) 2010 Free Software Foundation, Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+at your option any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+@section Documentation license I
+@anchor{Documentation license I}
+
+Permission is granted to copy, distribute and/or modify this documentation
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the file fdl.txt.
+
+@section Documentation license II
+@anchor{Documentation license II}
+
+You are free:
+
+@table @asis
+@item @strong{to Share}
+@anchor{@strong{to Share}}
+
+to copy, distribute and transmit the work
+
+@item @strong{to Remix}
+@anchor{@strong{to Remix}}
+
+to adapt the work
+
+@end table
+
+Under the following conditions:
+
+@table @asis
+@item @strong{Attribution}
+@anchor{@strong{Attribution}}
+
+You must attribute the work in the manner specified by the author or
+licensor (but not in any way that suggests that they endorse you or
+your use of the work).
+
+@item @strong{Share Alike}
+@anchor{@strong{Share Alike}}
+
+If you alter, transform, or build upon this work, you may distribute
+the resulting work only under the same, similar or a compatible
+license.
+
+@end table
+
+With the understanding that:
+
+@table @asis
+@item @strong{Waiver}
+@anchor{@strong{Waiver}}
+
+Any of the above conditions can be waived if you get permission from
+the copyright holder.
+
+@item @strong{Public Domain}
+@anchor{@strong{Public Domain}}
+
+Where the work or any of its elements is in the public domain under
+applicable law, that status is in no way affected by the license.
+
+@item @strong{Other Rights}
+@anchor{@strong{Other Rights}}
+
+In no way are any of the following rights affected by the license:
+
+@itemize
+@item Your fair dealing or fair use rights, or other applicable
+copyright exceptions and limitations;
+
+@item The author's moral rights;
+
+@item Rights other persons may have either in the work itself or in
+how the work is used, such as publicity or privacy rights.
+
+@end itemize
+
+@end table
+
+@table @asis
+@item @strong{Notice}
+@anchor{@strong{Notice}}
+
+For any reuse or distribution, you must make clear to others the
+license terms of this work.
+
+@end table
+
+A copy of the full license is included in the file as cc-by-sa.txt.
+
+@chapter DEPENDENCIES
+@anchor{DEPENDENCIES}
+
+GNU @strong{niceload} uses Perl, and the Perl modules POSIX, and
+Getopt::Long.
+
+@chapter SEE ALSO
+@anchor{SEE ALSO}
+
+@strong{parallel}(1), @strong{nice}(1), @strong{uptime}(1)
+
+@bye

src/parallel

@@ -543,7 +543,7 @@ sub get_options_from_array {
 sub parse_options {
     # Returns: N/A
     # Defaults:
-    $Global::version = 20120122;
+    $Global::version = 20120124;
     $Global::progname = 'parallel';
     $Global::infinity = 2**31;
     $Global::debug = 0;

src/sem.texi

@@ -0,0 +1,339 @@
+\input texinfo
+@setfilename sem.info
+
+@documentencoding utf-8
+
+@settitle sem - semaphore for executing shell command lines in parallel
+
+@node Top
+@top sem
+
+@chapter NAME
+@anchor{NAME}
+
+sem - semaphore for executing shell command lines in parallel
+
+@chapter SYNOPSIS
+@anchor{SYNOPSIS}
+
+@strong{sem} [--fg] [--id <id>] [--timeout <secs>] [-j <num>] [--wait] command
+
+@chapter DESCRIPTION
+@anchor{DESCRIPTION}
+
+GNU @strong{sem} is an alias for GNU @strong{parallel --semaphore}.
+
+It works as a tool for executing shell commands in parallel. GNU
+@strong{sem} acts as a counting semaphore. When GNU @strong{sem} is called with
+command it will start the command in the background. When @emph{num}
+number of commands are running in the background, GNU @strong{sem} will wait
+for one of these to complete before starting another command.
+
+Before looking at the options you may want to check out the examples
+after the list of options. That will give you an idea of what GNU
+@strong{sem} is capable of.
+
+@chapter OPTIONS
+@anchor{OPTIONS}
+
+@table @asis
+@item @emph{command}
+@anchor{@emph{command}}
+
+Command to execute. The command may be followed by arguments for the command.
+
+@item @strong{--bg}
+@anchor{@strong{--bg}}
+
+Run command in background thus GNU @strong{parallel} will not wait for
+completion of the command before exiting. This is the default.
+
+See also: @strong{--fg}
+
+@item @strong{-j} @emph{N}
+@anchor{@strong{-j} @emph{N}}
+
+Run up to N commands in parallel. Default is 1 thus acting like a
+mutex.
+
+@item @strong{--jobs} @emph{N}
+@anchor{@strong{--jobs} @emph{N}}
+
+@item @strong{-j} @emph{N}
+@anchor{@strong{-j} @emph{N} 1}
+
+@item @strong{--max-procs} @emph{N}
+@anchor{@strong{--max-procs} @emph{N}}
+
+@item @strong{-P} @emph{N}
+@anchor{@strong{-P} @emph{N}}
+
+Run up to N commands in parallel. Default is 1 thus acting like a
+mutex.
+
+@item @strong{--jobs} @emph{+N}
+@anchor{@strong{--jobs} @emph{+N}}
+
+@item @strong{-j} @emph{+N}
+@anchor{@strong{-j} @emph{+N}}
+
+@item @strong{--max-procs} @emph{+N}
+@anchor{@strong{--max-procs} @emph{+N}}
+
+@item @strong{-P} @emph{+N}
+@anchor{@strong{-P} @emph{+N}}
+
+Add N to the number of CPU cores.  Run up to this many jobs in
+parallel. For compute intensive jobs @strong{-j} +0 is useful as it will run
+number-of-cpu-cores jobs simultaneously.
+
+@item @strong{--jobs} @emph{-N}
+@anchor{@strong{--jobs} @emph{-N}}
+
+@item @strong{-j} @emph{-N}
+@anchor{@strong{-j} @emph{-N}}
+
+@item @strong{--max-procs} @emph{-N}
+@anchor{@strong{--max-procs} @emph{-N}}
+
+@item @strong{-P} @emph{-N}
+@anchor{@strong{-P} @emph{-N}}
+
+Subtract N from the number of CPU cores.  Run up to this many jobs in
+parallel.  If the evaluated number is less than 1 then 1 will be used.
+See also @strong{--use-cpus-instead-of-cores}.
+
+@item @strong{--jobs} @emph{N}%
+@anchor{@strong{--jobs} @emph{N}%}
+
+@item @strong{-j} @emph{N}%
+@anchor{@strong{-j} @emph{N}%}
+
+@item @strong{--max-procs} @emph{N}%
+@anchor{@strong{--max-procs} @emph{N}%}
+
+@item @strong{-P} @emph{N}%
+@anchor{@strong{-P} @emph{N}%}
+
+Multiply N% with the number of CPU cores.  Run up to this many jobs in
+parallel.  If the evaluated number is less than 1 then 1 will be used.
+See also @strong{--use-cpus-instead-of-cores}.
+
+@item @strong{--jobs} @emph{procfile}
+@anchor{@strong{--jobs} @emph{procfile}}
+
+@item @strong{-j} @emph{procfile}
+@anchor{@strong{-j} @emph{procfile}}
+
+@item @strong{--max-procs} @emph{procfile}
+@anchor{@strong{--max-procs} @emph{procfile}}
+
+@item @strong{-P} @emph{procfile}
+@anchor{@strong{-P} @emph{procfile}}
+
+Read parameter from file. Use the content of @emph{procfile} as parameter
+for @emph{-j}. E.g. @emph{procfile} could contain the string 100% or +2 or
+10.
+
+@item @strong{--semaphorename} @emph{name}
+@anchor{@strong{--semaphorename} @emph{name}}
+
+@item @strong{--id} @emph{name}
+@anchor{@strong{--id} @emph{name}}
+
+Use @strong{name} as the name of the semaphore. Default is the name of the
+controlling tty (output from @strong{tty}).
+
+The default normally works as expected when used interactively, but
+when used in a script @emph{name} should be set. @emph{$$} or @emph{my_task_name}
+are often a good value.
+
+The semaphore is stored in ~/.parallel/semaphores/
+
+@item @strong{--fg}
+@anchor{@strong{--fg}}
+
+Do not put command in background.
+
+@item @strong{--timeout} @emph{secs} (not implemented)
+@anchor{@strong{--timeout} @emph{secs} (not implemented)}
+
+@item @strong{-t} @emph{secs} (not implemented)
+@anchor{@strong{-t} @emph{secs} (not implemented)}
+
+If the semaphore is not released within @emph{secs} seconds, take it anyway.
+
+@item @strong{--wait}
+@anchor{@strong{--wait}}
+
+@item @strong{-w}
+@anchor{@strong{-w}}
+
+Wait for all commands to complete.
+
+@end table
+
+@chapter EXAMPLE: Gzipping *.log
+@anchor{EXAMPLE: Gzipping *.log}
+
+Run one gzip process per CPU core. Block until a CPU core becomes
+available.
+
+@verbatim
+  for i in `ls *.log` ; do
+    echo $i
+    sem -j+0 gzip $i ";" echo done
+  done
+  sem --wait
+@end verbatim
+
+@chapter EXAMPLE: Protecting pod2html from itself
+@anchor{EXAMPLE: Protecting pod2html from itself}
+
+pod2html creates two files: pod2htmd.tmp and pod2htmi.tmp which it
+does not clean up. It uses these two files for a short time. But if
+you run multiple pod2html in parallel (e.g. in a Makefile with make
+-j) you need to protect pod2html from running twice at the same
+time. @strong{sem} running as a mutex will do just that:
+
+@verbatim
+  sem --fg --id pod2html pod2html foo.pod > foo.html
+  sem --fg --id pod2html rm -f pod2htmd.tmp pod2htmi.tmp
+@end verbatim
+
+@chapter BUGS
+@anchor{BUGS}
+
+None known.
+
+@chapter REPORTING BUGS
+@anchor{REPORTING BUGS}
+
+Report bugs to <bug-parallel@@gnu.org>.
+
+@chapter AUTHOR
+@anchor{AUTHOR}
+
+Copyright (C) 2010,2011 Ole Tange, http://ole.tange.dk and Free
+Software Foundation, Inc.
+
+@chapter LICENSE
+@anchor{LICENSE}
+
+Copyright (C) 2010,2011 Free Software Foundation, Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+at your option any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+@section Documentation license I
+@anchor{Documentation license I}
+
+Permission is granted to copy, distribute and/or modify this documentation
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the file fdl.txt.
+
+@section Documentation license II
+@anchor{Documentation license II}
+
+You are free:
+
+@table @asis
+@item @strong{to Share}
+@anchor{@strong{to Share}}
+
+to copy, distribute and transmit the work
+
+@item @strong{to Remix}
+@anchor{@strong{to Remix}}
+
+to adapt the work
+
+@end table
+
+Under the following conditions:
+
+@table @asis
+@item @strong{Attribution}
+@anchor{@strong{Attribution}}
+
+You must attribute the work in the manner specified by the author or
+licensor (but not in any way that suggests that they endorse you or
+your use of the work).
+
+@item @strong{Share Alike}
+@anchor{@strong{Share Alike}}
+
+If you alter, transform, or build upon this work, you may distribute
+the resulting work only under the same, similar or a compatible
+license.
+
+@end table
+
+With the understanding that:
+
+@table @asis
+@item @strong{Waiver}
+@anchor{@strong{Waiver}}
+
+Any of the above conditions can be waived if you get permission from
+the copyright holder.
+
+@item @strong{Public Domain}
+@anchor{@strong{Public Domain}}
+
+Where the work or any of its elements is in the public domain under
+applicable law, that status is in no way affected by the license.
+
+@item @strong{Other Rights}
+@anchor{@strong{Other Rights}}
+
+In no way are any of the following rights affected by the license:
+
+@itemize
+@item Your fair dealing or fair use rights, or other applicable
+copyright exceptions and limitations;
+
+@item The author's moral rights;
+
+@item Rights other persons may have either in the work itself or in
+how the work is used, such as publicity or privacy rights.
+
+@end itemize
+
+@end table
+
+@table @asis
+@item @strong{Notice}
+@anchor{@strong{Notice}}
+
+For any reuse or distribution, you must make clear to others the
+license terms of this work.
+
+@end table
+
+A copy of the full license is included in the file as cc-by-sa.txt.
+
+@chapter DEPENDENCIES
+@anchor{DEPENDENCIES}
+
+GNU @strong{sem} uses Perl, and the Perl modules Getopt::Long,
+Symbol, Fcntl.
+
+@chapter SEE ALSO
+@anchor{SEE ALSO}
+
+@strong{parallel}(1)
+
+@bye

src/sql

@@ -556,7 +556,7 @@ $Global::Initfile && unlink $Global::Initfile;
 exit ($err);
 
 sub parse_options {
-    $Global::version = 20120122;
+    $Global::version = 20120124;
     $Global::progname = 'sql';
 
     # This must be done first as this may exec myself

src/sql.texi

@@ -0,0 +1,501 @@
+\input texinfo
+@setfilename sql.info
+
+@documentencoding utf-8
+
+@settitle sql - execute a command on a database determined by a dburl
+
+@node Top
+@top sql
+
+@chapter NAME
+@anchor{NAME}
+
+sql - execute a command on a database determined by a dburl
+
+@chapter SYNOPSIS
+@anchor{SYNOPSIS}
+
+@strong{sql} [options] @emph{dburl} [@emph{commands}]
+
+@strong{sql} [options] @emph{dburl} < commandfile
+
+@strong{#!/usr/bin/sql} @strong{--shebang} [options] @emph{dburl}
+
+@chapter DESCRIPTION
+@anchor{DESCRIPTION}
+
+GNU @strong{sql} aims to give a simple, unified interface for accessing
+databases through all the different databases' command line
+clients. So far the focus has been on giving a common way to specify
+login information (protocol, username, password, hostname, and port
+number), size (database and table size), and running queries.
+
+The database is addressed using a DBURL. If @emph{commands} are left out
+you will get that database's interactive shell.
+
+GNU @strong{sql} is often used in combination with GNU @strong{parallel}.
+
+@table @asis
+@item @emph{dburl}
+@anchor{@emph{dburl}}
+
+A DBURL has the following syntax:
+[sql:]vendor://
+[[user][:password]@@][host][:port]/[database][?sqlquery]
+
+See the section DBURL below.
+
+@item @emph{commands}
+@anchor{@emph{commands}}
+
+The SQL commands to run. Each argument will have a newline
+appended.
+
+Example: "SELECT * FROM foo;" "SELECT * FROM bar;"
+
+If the arguments contain '\n' or '\x0a' this will be replaced with a
+newline:
+
+Example: "SELECT * FROM foo;\n SELECT * FROM bar;"
+
+If no commands are given SQL is read from the keyboard or STDIN.
+
+Example: echo 'SELECT * FROM foo;' | sql mysql:///
+
+@item @strong{--db-size}
+@anchor{@strong{--db-size}}
+
+@item @strong{--dbsize}
+@anchor{@strong{--dbsize}}
+
+Size of database. Show the size of the database on disk. For Oracle
+this requires access to read the table @emph{dba_data_files} - the user
+@emph{system} has that.
+
+@item @strong{--help}
+@anchor{@strong{--help}}
+
+@item @strong{-h}
+@anchor{@strong{-h}}
+
+Print a summary of the options to GNU @strong{sql} and exit.
+
+@item @strong{--html}
+@anchor{@strong{--html}}
+
+HTML output. Turn on HTML tabular output.
+
+@item @strong{--show-processlist}
+@anchor{@strong{--show-processlist}}
+
+@item @strong{--proclist}
+@anchor{@strong{--proclist}}
+
+@item @strong{--listproc}
+@anchor{@strong{--listproc}}
+
+Show the list of running queries.
+
+@item @strong{--show-databases}
+@anchor{@strong{--show-databases}}
+
+@item @strong{--showdbs}
+@anchor{@strong{--showdbs}}
+
+@item @strong{--list-databases}
+@anchor{@strong{--list-databases}}
+
+@item @strong{--listdbs}
+@anchor{@strong{--listdbs}}
+
+List the databases (table spaces) in the database.
+
+@item @strong{--show-tables}
+@anchor{@strong{--show-tables}}
+
+@item @strong{--list-tables}
+@anchor{@strong{--list-tables}}
+
+@item @strong{--table-list}
+@anchor{@strong{--table-list}}
+
+List the tables in the database.
+
+@item @strong{--noheaders}
+@anchor{@strong{--noheaders}}
+
+@item @strong{--no-headers}
+@anchor{@strong{--no-headers}}
+
+@item @strong{-n}
+@anchor{@strong{-n}}
+
+Remove headers and footers and print only tuples. Bug in Oracle: it
+still prints number of rows found.
+
+@item @strong{-p} @emph{pass-through}
+@anchor{@strong{-p} @emph{pass-through}}
+
+The string following -p will be given to the database connection
+program as arguments. Multiple -p's will be joined with
+space. Example: pass '-U' and the user name to the program:
+
+@emph{-p "-U scott"} can also be written @emph{-p -U -p scott}.
+
+@item @strong{-r}
+@anchor{@strong{-r}}
+
+Try 3 times. Short version of @emph{--retries 3}.
+
+@item @strong{--retries} @emph{ntimes}
+@anchor{@strong{--retries} @emph{ntimes}}
+
+Try @emph{ntimes} times. If the client program returns with an error,
+retry the command. Default is @emph{--retries 1}.
+
+@item @strong{--sep} @emph{string}
+@anchor{@strong{--sep} @emph{string}}
+
+@item @strong{-s} @emph{string}
+@anchor{@strong{-s} @emph{string}}
+
+Field separator. Use @emph{string} as separator between columns.
+
+@item @strong{--skip-first-line}
+@anchor{@strong{--skip-first-line}}
+
+Do not use the first line of input (used by GNU @strong{sql} itself
+when called with @strong{--shebang}).
+
+@item @strong{--table-size}
+@anchor{@strong{--table-size}}
+
+@item @strong{--tablesize}
+@anchor{@strong{--tablesize}}
+
+Size of tables. Show the size of the tables in the database.
+
+@item @strong{--version}
+@anchor{@strong{--version}}
+
+@item @strong{-V}
+@anchor{@strong{-V}}
+
+Print the version GNU @strong{sql} and exit.
+
+@item @strong{--shebang}
+@anchor{@strong{--shebang}}
+
+@item @strong{-Y}
+@anchor{@strong{-Y}}
+
+GNU @strong{sql} can be called as a shebang (#!) command as the first line of a script. Like this:
+
+@verbatim
+  #!/usr/bin/sql -Y mysql:///
+
+  SELECT * FROM foo;
+@end verbatim
+
+For this to work @strong{--shebang} or @strong{-Y} must be set as the first option.
+
+@end table
+
+@chapter DBURL
+@anchor{DBURL}
+
+A DBURL has the following syntax:
+[sql:]vendor://
+[[user][:password]@@][host][:port]/[database][?sqlquery]
+
+To quote special characters use %-encoding specified in
+http://tools.ietf.org/html/rfc3986#section-2.1 (E.g. a password
+containing '/' would contain '%2F').
+
+Examples:
+ mysql://scott:tiger@@my.example.com/mydb
+ sql:oracle://scott:tiger@@ora.example.com/xe
+ postgresql://scott:tiger@@pg.example.com/pgdb
+ pg:///
+ postgresqlssl://scott@@pg.example.com:3333/pgdb
+ sql:sqlite2:////tmp/db.sqlite?SELECT * FROM foo;
+ sqlite3:///../db.sqlite3?SELECT%20*%20FROM%20foo;
+
+Currently supported vendors: MySQL (mysql), MySQL with SSL (mysqls,
+mysqlssl), Oracle (oracle, ora), PostgreSQL (postgresql, pg, pgsql,
+postgres), PostgreSQL with SSL (postgresqlssl, pgs, pgsqlssl,
+postgresssl, pgssl, postgresqls, pgsqls, postgress), SQLite2 (sqlite,
+sqlite2), SQLite3 (sqlite3).
+
+Aliases must start with ':' and are read from 
+/etc/sql/aliases and ~/.sql/aliases. The user's own
+~/.sql/aliases should only be readable by the user.
+
+Example of aliases:
+
+@verbatim
+ :myalias1 pg://scott:tiger@pg.example.com/pgdb
+ :myalias2 ora://scott:tiger@ora.example.com/xe
+ # Short form of mysql://`whoami`:nopassword@localhost:3306/`whoami`
+ :myalias3 mysql:///
+ # Short form of mysql://`whoami`:nopassword@localhost:33333/mydb
+ :myalias4 mysql://:33333/mydb
+ # Alias for an alias
+ :m      :myalias4
+ # the sortest alias possible
+ :       sqlite2:////tmp/db.sqlite
+ # Including an SQL query
+ :query  sqlite:////tmp/db.sqlite?SELECT * FROM foo;
+@end verbatim
+
+@chapter EXAMPLES
+@anchor{EXAMPLES}
+
+@section Get an interactive prompt
+@anchor{Get an interactive prompt}
+
+The most basic use of GNU @strong{sql} is to get an interactive prompt:
+
+@strong{sql sql:oracle://scott:tiger@@ora.example.com/xe}
+
+If you have setup an alias you can do:
+
+@strong{sql :myora}
+
+@section Run a query
+@anchor{Run a query}
+
+To run a query directly from the command line:
+
+@strong{sql :myalias "SELECT * FROM foo;"}
+
+Oracle requires newlines after each statement. This can be done like
+this:
+
+@strong{sql :myora "SELECT * FROM foo;" "SELECT * FROM bar;"}
+
+Or this:
+
+@strong{sql :myora "SELECT * FROM foo;\nSELECT * FROM bar;"}
+
+@section Copy a PostgreSQL database
+@anchor{Copy a PostgreSQL database}
+
+To copy a PostgreSQL database use pg_dump to generate the dump and GNU
+@strong{sql} to import it:
+
+@strong{pg_dump pg_database | sql pg://scott:tiger@@pg.example.com/pgdb}
+
+@section Empty all tables in a MySQL database
+@anchor{Empty all tables in a MySQL database}
+
+Using GNU @strong{parallel} it is easy to empty all tables without dropping them:
+
+@strong{sql -n mysql:/// 'show tables' | parallel sql mysql:/// DELETE FROM @{@};}
+
+@section Drop all tables in a PostgreSQL database
+@anchor{Drop all tables in a PostgreSQL database}
+
+To drop all tables in a PostgreSQL database do:
+
+@strong{sql -n pg:/// '\dt' | parallel --colsep '\|' -r sql pg:/// DROP TABLE @{2@};}
+
+@section Run as a script
+@anchor{Run as a script}
+
+Instead of doing:
+
+@strong{sql mysql:/// < sqlfile}
+
+you can combine the sqlfile with the DBURL to make a
+UNIX-script. Create a script called @emph{demosql}:
+
+@strong{#!/usr/bin/sql -Y mysql:///}
+
+@strong{SELECT * FROM foo;}
+
+Then do:
+
+@strong{chmod +x demosql; ./demosql}
+
+@section Use --colsep to process multiple columns
+@anchor{Use --colsep to process multiple columns}
+
+Use GNU @strong{parallel}'s @strong{--colsep} to separate columns:
+
+@strong{sql -s '\t' :myalias 'SELECT * FROM foo;' | parallel --colsep '\t' do_stuff @{4@} @{1@}}
+
+@section Retry if the connection fails
+@anchor{Retry if the connection fails}
+
+If the access to the database fails occationally @strong{--retries} can help
+make sure the query succeeds:
+
+@strong{sql --retries 5 :myalias 'SELECT * FROM really_big_foo;'}
+
+@section Get info about the running database system
+@anchor{Get info about the running database system}
+
+Show how big the database is:
+
+@strong{sql --db-size :myalias}
+
+List the tables:
+
+@strong{sql --list-tables :myalias}
+
+List the size of the tables:
+
+@strong{sql --table-size :myalias}
+
+List the running processes:
+
+@strong{sql --show-processlist :myalias}
+
+@chapter REPORTING BUGS
+@anchor{REPORTING BUGS}
+
+GNU @strong{sql} is part of GNU @strong{parallel}. Report bugs to <bug-parallel@@gnu.org>.
+
+@chapter AUTHOR
+@anchor{AUTHOR}
+
+When using GNU @strong{sql} for a publication please cite:
+
+O. Tange (2011): GNU SQL - A Command Line Tool for Accessing Different
+Databases Using DBURLs, ;login: The USENIX Magazine, April 2011:29-32.
+
+Copyright (C) 2008,2009,2010 Ole Tange http://ole.tange.dk
+
+Copyright (C) 2010,2011 Ole Tange, http://ole.tange.dk and Free
+Software Foundation, Inc.
+
+@chapter LICENSE
+@anchor{LICENSE}
+
+Copyright (C) 2007,2008,2009,2010,2011 Free Software Foundation, Inc.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+at your option any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+@section Documentation license I
+@anchor{Documentation license I}
+
+Permission is granted to copy, distribute and/or modify this documentation
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the file fdl.txt.
+
+@section Documentation license II
+@anchor{Documentation license II}
+
+You are free:
+
+@table @asis
+@item @strong{to Share}
+@anchor{@strong{to Share}}
+
+to copy, distribute and transmit the work
+
+@item @strong{to Remix}
+@anchor{@strong{to Remix}}
+
+to adapt the work
+
+@end table
+
+Under the following conditions:
+
+@table @asis
+@item @strong{Attribution}
+@anchor{@strong{Attribution}}
+
+You must attribute the work in the manner specified by the author or
+licensor (but not in any way that suggests that they endorse you or
+your use of the work).
+
+@item @strong{Share Alike}
+@anchor{@strong{Share Alike}}
+
+If you alter, transform, or build upon this work, you may distribute
+the resulting work only under the same, similar or a compatible
+license.
+
+@end table
+
+With the understanding that:
+
+@table @asis
+@item @strong{Waiver}
+@anchor{@strong{Waiver}}
+
+Any of the above conditions can be waived if you get permission from
+the copyright holder.
+
+@item @strong{Public Domain}
+@anchor{@strong{Public Domain}}
+
+Where the work or any of its elements is in the public domain under
+applicable law, that status is in no way affected by the license.
+
+@item @strong{Other Rights}
+@anchor{@strong{Other Rights}}
+
+In no way are any of the following rights affected by the license:
+
+@itemize
+@item Your fair dealing or fair use rights, or other applicable
+copyright exceptions and limitations;
+
+@item The author's moral rights;
+
+@item Rights other persons may have either in the work itself or in
+how the work is used, such as publicity or privacy rights.
+
+@end itemize
+
+@item @strong{Notice}
+@anchor{@strong{Notice}}
+
+For any reuse or distribution, you must make clear to others the
+license terms of this work.
+
+@end table
+
+A copy of the full license is included in the file as cc-by-sa.txt.
+
+@chapter DEPENDENCIES
+@anchor{DEPENDENCIES}
+
+GNU @strong{sql} uses Perl. If @strong{mysql} is installed, MySQL dburls will
+work. If @strong{psql} is installed, PostgreSQL dburls will work.  If
+@strong{sqlite} is installed, SQLite2 dburls will work.  If @strong{sqlite3} is
+installed, SQLite3 dburls will work. If @strong{sqlplus} is installed,
+Oracle dburls will work. If @strong{rlwrap} is installed, GNU @strong{sql} will
+have a command history for Oracle.
+
+@chapter FILES
+@anchor{FILES}
+
+~/.sql/aliases - user's own aliases with DBURLs
+
+/etc/sql/aliases - common aliases with DBURLs
+
+@chapter SEE ALSO
+@anchor{SEE ALSO}
+
+@strong{mysql}(1), @strong{psql}(1), @strong{rlwrap}(1), @strong{sqlite}(1), @strong{sqlite3}(1), @strong{sqlplus}(1)
+
+@bye