.TH UCF-HELPER-FUNCTIONS 5 "2026-06-04" "Debian" "Debian GNU/Linux  Manual"
.SH NAME
ucf-helper-functions.sh \- POSIX shell helper library for ucf-based configuration management

.SH DESCRIPTION
The file
.I ucf-helper-functions.sh
is a shell library used by Debian maintainer scripts to manage configuration
files via
.B ucf
and
.B ucfr.

It provides higher-level abstractions for:

.IP \(bu 2
Installing and updating configuration files shipped by a package
.IP \(bu 2
Preserving local administrator modifications
.IP \(bu 2
Detecting ownership of configuration files across packages
.IP \(bu 2
Handling file removal and migration across package versions
.IP \(bu 2
Reconciling package state with system state

.PP
The library is intended to be sourced from maintainer scripts such as
.I postinst
and
.I postrm.

.SH ENVIRONMENT

.TP
.B PKGNAME
Name of the owning Debian package. Required for correct registration with
.B ucfr.

.SH FUNCTIONS

.SS rename_ucf_file oldname newname
Renames a configuration file managed by
.B ucf
and updates registration state in
.B ucfr.

Also updates internal
.I /var/lib/ucf/hashfile
entries to reflect the rename.

This function is used during package upgrades where configuration file paths
change between versions.
The actual file rename of the "New File" delivered
with the package must already have happened.

.SS handle_single_ucf_file pkgfile locfile
Processes a single configuration file shipped by the package.

It invokes
.B ucf
for merge handling.

.SS handle_deleted_ucf_file locfile pkgdir locdir
Handles configuration files removed from the package in newer versions.

If the corresponding file in
.I pkgdir
no longer exists:

.IP \(bu 2
Runs
.B ucf
against /dev/null to trigger merge logic
.IP \(bu 2
Removes file if it becomes empty after processing
.IP \(bu 2
Removes known dpkg/ucf backup variants
.IP \(bu 2
Purges registrations from
.B ucf
and
.B ucfr

.PP
Local modifications are preserved unless the file becomes empty.

.SS handle_all_ucf_files pkgdir locdir
Main entry point for configuration file/directory processing.

It performs:

.IP \(bu 2
Creation of target directory structure
.IP \(bu 2
Processing of all package-shipped file in the pkgdir.
.IP \(bu 2
Detection and handling of removed files
.IP \(bu 2
Synchronization of ucf state with filesystem state

.SH IMPLEMENTATION NOTES

This library assumes a POSIX-compatible shell (Debian dash-compatible)
and a reasonable GNU userland as usually present on a Debian system.

.SH EXAMPLES

You ship all your package configuration files to be managed via ucf
in /usr/share/examplepkg/config.
Then you modify your maintainer scripts like this:

.SS Basic postinst integration

.nf
.in +4
#!/bin/sh
set -e

PKGNAME="examplepkg"

\&. /usr/share/examplepkg/ucf-helper-functions.sh

SRCDIR="/usr/share/${PKGNAME}/config"
TRGDIR="/etc"

case "$1" in
    configure)
        handle_all_ucf_files "$SRCDIR" "$TRGDIR"
        ;;
esac

exit 0
.in -4
.fi

.SS Renaming configuration files across versions

.nf
.in +4
if dpkg --compare-versions "$2" le 0.16-1; then
    rename_ucf_file \\
        /etc/example/conf.d/old \\
        /etc/example/conf.d/new
fi
.in -4
.fi

.SH SEE ALSO
.BR ucf (1),
.BR ucfr (1),
.BR ucfq (1),
.BR dpkg (1),
.BR dash (1)

.SH AUTHOR
This manual page was written by Marc Haber <mh+debian-packages@zugschlus.de>
for the Debian GNU/Linux system.