singleton

#!/usr/bin/env bash
#
# Requirement:
#   - flock
#
# Author: James Cherti
# URL: https://github.com/jamescherti/bash-stdops
#
# Description:
# ------------
# This script functions as a mutual exclusion wrapper. It prevents concurrent
# executions of the same operation by using a dedicated lockfile.
#
# Usage Example:
#   singleton /var/run/backup.lock /usr/local/bin/backup.sh --verbose
#
# The above command prevents concurrent executions of the
# /usr/local/bin/backup.sh script. Running the command a second time while the
# first instance is active results in an error message and a non-zero exit code,
# which prevents multiple executions:
#   singleton /var/run/backup.lock /usr/local/bin/backup.sh --verbose
#
# Here is the error message caused by the second execution:
#   Error: Another instance of '/usr/local/bin/backup.sh' is running.
#
# License:
# --------
# Copyright (C) 2012-2026 James Cherti
#
# Distributed under terms of the GNU General Public License version 3.
#
# 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 <https://www.gnu.org/licenses/>.
#

set -euf -o pipefail

main() {
  if [[ $# -lt 2 ]]; then
    printf "Usage: %s <lockfile> <command> [args...]\n" "$0" >&2
    exit 1
  fi

  local lockfile="$1"
  shift
  local -a cmd=("$@")
  local command_name="${cmd[0]}"

  # Ensure secure permissions for the lockfile creation
  local old_umask
  old_umask=$(umask)
  umask 077

  # Open file descriptor for the lockfile
  local lockfd
  exec {lockfd}>"$lockfile"
  umask "$old_umask"

  # Attempt to acquire an exclusive, non-blocking lock
  if ! flock -x -n "$lockfd"; then
    printf "Error: Another instance of '%s' is running.\n" "$command_name" >&2
    exit 1
  fi

  # Release the lock when the shell exits.
  # shellcheck disable=SC2064
  trap "exec $lockfd>&-" EXIT

  # Execute the provided command
  "${cmd[@]}"
}

main "$@"