www.voj-tech.net


vt-bash-utils

Synopsis

vt-bash-utils are Bash scripts providing general purpose utility functions.

Code Example

vtbu_send_desktop_notification

#!/usr/bin/env bash

bash_utils_path='/usr/local/share/vt-bash-utils'
source "$bash_utils_path/desktop-notifications.sh"

summary='Hello World!'
body=''
urgency='normal'
app_name='my-script'
icon='dialog-information'
category=''

vtbu_send_desktop_notification "$summary" "$body" "$urgency" "$app_name" "$icon" "$category"

vtbu_single_instance_running

#!/usr/bin/env bash

bash_utils_path='/usr/local/share/vt-bash-utils'
source "$bash_utils_path/single-instance.sh"

lock_filename='/tmp/my-script.lock'

script_name="$(basename "$0")"

if ! vtbu_single_instance_running "$lock_filename"; then
    echo "$script_name: Script is already running." >&2
    exit 1
fi

# proceed with your script here

Motivation

It was really the practicality of moving code which was common among a number of scripts presented on this website to shared files that led to creating this library.

The reason behind wrapping the notify-send command line utility without adding any extra functionality was to avoid making changes to all the scripts sending desktop notifications should the standard way of doing so change in the future.

Installation

Prerequisites

It is required that your environment features reasonably new versions of:

  • the notify-send command line utility (required by the function vtbu_send_desktop_notification)
  • the flock command line utility (required by the function vtbu_single_instance_running)
  • Bash

It should be noted that the library has been tested using libnotify 0.7.7 (provides the notify-send utility), util-linux 2.32.1 (provides the flock utility) and Bash 4.4.23 on Fedora 29.

Installation Steps

Although it is currently required to perform a manual installation it is rather trivial. To install the library follow these steps:

  1. Download a ZIP file with the required version of the library from this page. Most likely you want the latest version.

  2. Unpack the downloaded file.

    unzip vt-bash-utils-0.9.2.zip
    
  3. Copy the vt-bash-utils directory to a directory where other shell scripts will look for it. This might be the /usr/local/share directory for example. Make sure this is done as a user account allowed to write to the destination directory.

    cp -R vt-bash-utils-0.9.2/vt-bash-utils /usr/local/share
    

Note that it is not necessary to add the execute mode bit to the shell script files' mode bits since the files will be executed using the source built-in command in an existing shell.

Reference

There are two Bash script files in the library which can be used; desktop-notifications.sh and single-instance.sh. To use the functionality provided by one of these files in your script execute the file using the source built-in command. You will need to specify the relative or absolute path to the script.

desktop-notifications.sh

This file provides the function vtbu_send_desktop_notification.

vtbu_send_desktop_notification

Sends a desktop notification.

The function is a plain wrapper of the notify-send command line utility.

For more information on desktop notifications see the Desktop Notifications Specification.

Parameters
  1. Summary: A single line overview of the notification. It must be a non-empty string.
  2. Body: A multi-line body of text. If it is an empty string only the summary is displayed.
  3. Urgency Level: Defines the importance of the notification. It is one of 'low', 'normal' and 'critical'.
  4. Application Name: The name of the application sending the notification. It can be an empty string.
  5. Icon: The icon theme icon name or filename. It can be an empty string.
  6. Category: A comma separated list of the types of this notification. It can be an empty string.
Return Value

The exit status of the notify-send command. This is 0 if it succeeds, otherwise it is a value greater than 0.

Output

None.

single-instance.sh

This file provides the function vtbu_single_instance_running.

vtbu_single_instance_running

Checks whether the calling script is already running or not by trying to acquire an exclusive lock on a file.

The function assigns the file descriptor 200 to the locked file and attempts to lock the file using the command flock -n 200.

A fixed lock filename should be used to prevent running multiple instances of the same script on a system-wide level. A user dependent lock filename can be used to prevent running multiple instances of the same script on a per-user basis.

Parameters
  1. Lock Filename: Specifies the file to lock.
Return Value

The exit status of the flock command which uses sysexits.h. This is 0 if it succeeds, otherwise it is a value greater than 0.

Output

None.

Bugs

Suggestions and bug reports are more than welcome at voj-tech@voj-tech.net.