Appendix B. Examples Included with bash

The bash tarball includes a lot of material that is well worth exploring (after you’ve finished reading this book, of course). It includes sample code and examples, scripts, functions, and startup files. The easiest way to access this material is via our up-to-date list with hyperlinks, but we’re including this appendix to provide a taste of what you’ll find since few people actually access the tarball or build from source anymore.

bash Documentation and Examples

The startup-files directory provides many examples of what you can put in your own startup files. In particular, bash_aliases has many useful aliases. Bear in mind that if you copy these files wholesale, you’ll have to edit them for your system because many of the paths will be different. Refer to Chapter 16 for further information on changing these files to suit your needs.

The functions directory contains many function definitions that you might find useful. Among them are:

basename

The basename utility, missing from some systems.

dirfuncs

Directory manipulation facilities.

dirname

The dirname utility, missing from some systems.

whatis

An implementation of the Tenth Edition Bourne shell whatis builtin.

whence

An almost exact clone of the Korn shell whence builtin.

If you come from a Korn shell background, you may find kshenv especially helpful. This contains function definitions for some common Korn facilities such as whence, print, and the two-parameter cd builtins.

The scripts directory contains many examples of bash scripts. The two largest scripts are examples of the complex things you can do with shell scripts. The first is a (rather amusing) adventure game interpreter and the second is a C shell interpreter. The other scripts include examples of precedence rules, a scrolling text display, a “spinning wheel” progress display, and how to prompt the user for a particular type of answer.

Not only are the script and function examples useful for including in your environment, but they also provide many alternative examples that you can learn from in addition to reading this book. We encourage you to experiment with them.

Table B-1 is an index of what you will find as of bash 4.2.

Note

At the request of the Free Software Foundation, Chet removed some examples from recent versions of bash because there is some question about the provenance of the code. If an example you are interested in is missing, look for it in older releases or check http://www.bashcookbook.com/bashinfo/.

Table B-1. bash 4.2 documentation and examples
Path Description

./bash/ABOUT-NLS

Notes on the Free Translation Project

./bash/AUTHORS

Master author manifest for bash

./bash/CHANGES

DETAILED changes between versions

./bash/COMPAT

Incompatibilities between versions of bash

./bash/COPYING

GNU General Public License (various versions)

./bash/INSTALL

Basic installation instructions

./bash/MANIFEST

Master distribution manifest for bash

./bash/NEWS

A terse description of the new features added to bash

./bash/NOTES

Platform-specific configuration and operation notes

./bash/POSIX

Bash POSIX mode

./bash/RBASH

The restricted shell

./bash/README

bash high-level README

./bash/Y2K

Y2K notice

./bash/FAQ

The Bash FAQ

./bash/INTRO

A short introduction to bash

./bash/Makefile

Makefile for the Bash/documentation directory

./bash/README

bash documentation README

./bash/aosa-bash

Chapter 3: The Bourne-Again Shell from The Architecture of Open Source Applications, edited to trim length

./bash/aosa-bash-full

Chapter 3: The Bourne-Again Shell from The Architecture of Open Source Applications

./bash/article

An article Chet wrote about bash for The Linux Journal

./bash/bash

bash manpage

./bash/bashbug

bashbug manpage

./bash/bashref

The Bash Reference Manual

./bash/bashref_toc

Old Bash Reference Manual table of contents

./bash/builtins

builtins manpage, extracted from bash.1

./bash/fdl

GNU Free Documentation License

./bash/rbash

bash restricted shell manpage

./bash/readline

GNU readline manpage

./bash/rose94

Article: “Bash, the Bourne-Again Shell”

./bash/version

bash version info

./INDEX/INDEX

An index of bash examples (a subset of this)

./complete/bash_completion

Programmable completion functions

./complete/bashcc-1.0.1.tar

ClearCase completions from Richard Smith

./complete/cdfunc

An example completion function for cd

./complete/complete

Various completion files

./complete/complete-examples

Completion examples

./complete/complete2

Various completion files from Ian Macdonald

./functions/array-stuff

Various array functions (ashift, array_sort, reverse)

./functions/array-to-string

Converts an array to a string

./functions/autoload

An almost ksh-compatible autoload

./functions/basename

A replacement for basename(1)

./functions/basename2

Fast basename(1) and dirname(1) functions for bash/sh

./functions/coproc

Start, control, and end coprocesses

./functions/coshell

Control shell coprocesses (see coprocess.bash)

./functions/csh-compat

A C shell compatibility package

./functions/dirfuncs

Directory manipulation functions from the book The Korn Shell

./functions/dirname

A replacement for dirname(1)

./functions/dirstack

Another implementation of the directory manipulation functions from the book The New KornShell Command and Programming Language

./functions/emptydir

Finds out if a directory is empty

./functions/exitstat

Displays the exit status of processes

./functions/external

Like command but FORCES use of external command

./functions/fact

A recursive factorial function

./functions/fstty

Frontend to sync TERM changes to both stty(1) and readline bind

./functions/func

Prints out definitions for functions named by arguments

./functions/gethtml

Gets a web page from a remote server (wget(1) in bash!)

./functions/getoptx

getopt function that parses long-named options

./functions/inetaddr

Performs internet address conversion (inet2hex & hex2inet)

./functions/inpath

Returns zero if the argument is in the path and executable

./functions/isnum

Tests user input on numeric or character values

./functions/isnum2

Tests user input on numeric values, with floating point

./functions/isvalidip

Tests user input for valid IP addresses

./functions/jdate

A function for Julian date conversion

./functions/jj

Looks for running jobs

./functions/keep

Tries to keep some programs in the foreground and running

./functions/ksh-cd

ksh-like cd: cd [-LP] [dir [change]]

./functions/ksh-compat-test

ksh-like arithmetic test replacements

./functions/kshenv

Functions and aliases to provide the beginnings of a ksh environment for bash

./functions/login

Replaces the login and newgrp builtins in old Bourne shells

./functions/lowercase

Renames files to lowercase

./functions/manpage

Finds and prints a manual page

./functions/mhfold

Prints MH folders; useful only because folders(1) doesn’t print mod date/times

./functions/notify

Notifies when jobs change status

./functions/pathfuncs

Path-related functions (no_path, add_path, pre-path, del_path)

./functions/recurse

A recursive directory traverser

./functions/repeat2

A clone of C shell builtin repeat

./functions/repeat3

A clone of C shell builtin repeat

./functions/seq

Generates a sequence from m to n; m defaults to 1

./functions/seq2

Generates a sequence from m to n; m defaults to 1

./functions/shcat

A readline-based pager

./functions/shcat2

A readline-based pager

./functions/sort-pos-params

Sorts the positional parameters

./functions/substr

A function to emulate the ancient ksh builtin

./functions/substr2

A function to emulate the ancient ksh builtin

./functions/term

A shell function to set the terminal type interactively or not

./functions/whatis

An implementation of the 10th Edition Unix sh builtin whatis(1) command

./functions/whence

An almost-ksh-compatible whence(1) command

./functions/which

An emulation of which(1) as it appears in FreeBSD

./functions/xalias

Converts csh alias commands to bash functions

./functions/xfind

A find(1) clone

./loadables/Makefile

Simple Makefile for the sample loadable builtins

./loadables/Makefile.inc

Sample Makefile for bash loadable builtin development

./loadables/README

README

./loadables/basename

Returns the non-directory portion of a pathname

./loadables/cat

cat(1) replacement with no options—the way cat was intended

./loadables/cut

cut(1) replacement

./loadables/dirname

Returns the directory portion of a pathname

./loadables/finfo

Prints file info

./loadables/getconf

POSIX.2 getconf utility

./loadables/head

Copies the first part of a file

./loadables/hello

Obligatory “Hello World"/sample loadable

./loadables/id

POSIX.2 user identity

./loadables/ln

Makes links

./loadables/loadables

Includes files needed by all loadable builtins

./loadables/logname

Prints login name of current user

./loadables/mkdir

Makes directories

./loadables/mypid

Adds $MYPID as a shell builtin

./loadables/necho

echo without options or argument interpretation

./loadables/pathchk

Checks pathnames for validity and portability

./loadables/print

Loadable ksh-93-style print builtin

./loadables/printenv

Minimal built-in clone of BSD printenv(1)

./loadables/printf

Old printf

./loadables/push

Anyone remember TOPS-20?

./loadables/pushd

Old pushd

./loadables/realpath

Canonicalizes pathnames, resolving symlinks

./loadables/rmdir

Removes directories

./loadables/setpgid

bash loadable wrapper for setpgid system call

./loadables/sleep

Sleeps for fractions of a second

./loadables/sprintf

Old sprintf

./loadables/strftime

Loadable built-in interface to strftime(3)

./loadables/sync

Syncs the disks by forcing pending filesystem writes to complete

./loadables/tee

Duplicates standard input

./loadables/template

Example template for loadable builtin

./loadables/truefalse

True and false builtins

./loadables/tty

Returns the terminal name

./loadables/uname

Prints system information

./loadables/unlink

Removes a directory entry

./loadables/whoami

Prints out username of current user

./loadables/perl/Makefile

Makefile for built-in Perl interpreter

./loadables/perl/README

Illustrates how to build a Perl interpreter into bash

./loadables/perl/bperl

perl builtin

./loadables/perl/iperl

The Perl interpreter

./misc/aliasconv

Converts csh aliases to bash aliases and functions

./misc/cshtobash

Converts csh aliases, environment variables, and variables to bash equivalents

./misc/suncmd

SunView TERMCAP string

./obashdb/PERMISSION

Permission to use and distribute

./obashdb/README

Deprecated sample implementation of a bash debugger; see http://bashdb.sourceforge.net/ instead

./obashdb/bashdb

Deprecated bashdb (bash shell debugger); see http://bashdb.sourceforge.net/ instead

./scripts/adventure

Text adventure game in bash!

./scripts/bash-hexdump

hexdump(1) in bash

./scripts/bcsh

Bourne shell csh emulator

./scripts/cat

readline-based pager

./scripts/center

Centers a group of lines

./scripts/dd-ex

Line editor using only /bin/sh, /bin/dd, and /bin/rm

./scripts/fixfiles

Recurses a tree and fixes files containing various “bad” characters

./scripts/hanoi

The inevitable Towers of Hanoi in bash

./scripts/inpath

Searches $PATH for a file with the same name as $1; returns TRUE if found

./scripts/krand

Produces a random number within integer limits

./scripts/line-input

Line input routine for GNU Bourne Again shell plus terminal-control primitives

./scripts/nohup

bash version of nohup command

./scripts/precedence

Tests relative precedences for && and || operators

./scripts/randomcard

Prints a random card from a card deck

./scripts/scrollbar

Displays scrolling text

./scripts/scrollbar2

Displays scrolling text

./scripts/self-repro

A self-reproducing script (careful!)

./scripts/showperm

Converts ls(1) symbolic permissions into octal mode

./scripts/shprompt

Displays a prompt and gets an answer satisfying certain criteria

./scripts/spin

Displays a spinning wheel to show progress

./scripts/timeout

Gives rsh(1) a shorter timeout

./scripts/timeout2

Executes a given command with a timeout

./scripts/timeout3

Executes a given command with a timeout

./scripts/vtree2

Displays a tree printout of dir in 1k blocks

./scripts/vtree3

Displays a graphical tree printout of a directory

./scripts/vtree3a

Displays a graphical tree printout of a directory

./scripts/websrv

A web server in bash!

./scripts/xterm_title

Prints the contents of the xterm title bar

./scripts/zprintf

Emulates printf (obsolete since it’s now a bash builtin)

./scripts.noah/PERMISSION

Permissions to use the scripts in this directory

./scripts.noah/README

README

./scripts.noah/aref

Pseudoarrays and substring indexing examples

./scripts.noah/bash.sub

Library functions used by require.bash

./scripts.noah/bash_version

A function to slice up $BASH_VERSION

./scripts.noah/meta

Enables and disables eight-bit readline input

./scripts.noah/mktmp

Makes a temporary file with a unique name

./scripts.noah/number

A fun hack to translate numerals into English

./scripts.noah/prompt

A way to set $PS1 to some predefined strings

./scripts.noah/remap_keys

A frontend to bind to redo readline bindings

./scripts.noah/require

Lisp-like require/provide library functions for bash

./scripts.noah/send_mail

Replacement SMTP client written in bash

./scripts.noah/shcat

bash replacement for cat(1)

./scripts.noah/source

Replacement for source that uses current directory

./scripts.noah/string

The string(3) functions at the shell level

./scripts.noah/stty

Frontend to stty(1) that changes readline bindings too

./scripts.noah/y_or_n_p

Prompts for a yes/no/quit answer

./scripts.v2/PERMISSION

Permissions to use the scripts in this directory

./scripts.v2/README

README

./scripts.v2/arc2tarz

Converts an “arc” archive to a compressed tar archive

./scripts.v2/bashrand

Random number generator with upper and lower bounds and optional seed

./scripts.v2/cal2day

Converts a day number to a name

./scripts.v2/cdhist

cd replacement with a directory stack added

./scripts.v2/corename

Tells what produced a core file

./scripts.v2/fman

Fast man(1) replacement

./scripts.v2/frcp

Copies files using ftp(1) but with rcp-type command-line syntax

./scripts.v2/lowercase

Changes filenames to lowercase

./scripts.v2/ncp

A nicer frontend for cp(1) (has -i, etc.)

./scripts.v2/newext

Changes the extension of a group of files

./scripts.v2/nmv

A nicer frontend for mv(1) (has -i, etc.)

./scripts.v2/pages

Prints specified pages from files

./scripts.v2/pf

A pager frontend that handles compressed files

./scripts.v2/pmtop

Poor man’s top(1) for SunOS 4.x and BSD/OS

./scripts.v2/ren

Renames files by changing parts of filenames that match a pattern

./scripts.v2/rename

Changes the names of files that match a pattern

./scripts.v2/repeat

Executes a command multiple times

./scripts.v2/shprof

Line profiler for bash scripts

./scripts.v2/untar

Unarchives a (possibly compressed) tar archive into a directory

./scripts.v2/uudec

Carefully uudecodes multiple files

./scripts.v2/uuenc

uudecodes multiple files

./scripts.v2/vtree

Prints a visual display of a directory tree

./scripts.v2/where

Shows where commands that match a pattern are

./startup-files/Bash_aliases

Some useful aliases (Fox)

./startup-files/Bash_profile

Sample startup file for bash login shells (Fox)

./startup-files/Bashrc

Sample Bourne Again shell init file (Fox)

./startup-files/README

README

./startup-files/bash-profile

Sample startup file for bash login shells (Ramey)

./startup-files/bashrc

Sample Bourne Again shell init file (Ramey)

./startup-files/apple/README

README

./startup-files/apple/aliases

Sample aliases for macOS

./startup-files/apple/bash

Sample user preferences file

./startup-files/apple/environment

Sample Bourne Again shell environment file

./startup-files/apple/login

Sample login wrapper

./startup-files/apple/logout

Sample logout wrapper

./startup-files/apple/rc

Sample Bourne Again shell config file

./readline/CHANGELOG

readline-specific changelog

./readline/CHANGES

DETAILED changes between versions

./readline/COPYING

GNU General Public License (various versions)

./readline/INSTALL

Basic installation instructions

./readline/MANIFEST

Master distribution manifest for readline

./readline/NEWS

A terse description of the new features added to readline

./readline/README

bash high-level README

./readline/USAGE

A note on legal use of readline through a shared-library linking mechanism

./readline/Makefile

Makefile for the readline library documentation

./readline/fdl

GNU Free Documentation License

./readline/hist

readline history (seems to be only RL4.3)

./readline/history

GNU History library manpage

./readline/history_3

GNU History library manpage

./readline/history_toc

Old GNU History library

./readline/hstech

User interface to the GNU History library documentation

./readline/hsuser

User interface to the GNU History library documentation

./readline/manvers

Manuscript version (seems to be only RL4.3)

./readline/readline

GNU readline manpage

./readline/readline_3

readline docs

./readline/readline_toc

Old GNU readline library table of contents

./readline/rlman

The GNU readline library API

./readline/rltech

Programming with GNU readline

./readline/rluser

Command-line editing

./readline/rluserman

GNU readline library user manual

./readline/version

bash version info