1 # This is the X Strike Force shell library for X Window System package
2 # maintainer scripts. It serves to define shell functions commonly used by
3 # such packages, and performs some error checking necessary for proper operation
4 # of those functions. By itself, it does not "do" much; the maintainer scripts
5 # invoke the functions defined here to accomplish package installation and
8 # If you are reading this within a Debian package maintainer script (e.g.,
9 # /var/lib/dpkg/info/PACKAGE.{config,preinst,postinst,prerm,postrm}), you can
10 # skip past this library by scanning forward in this file to the string
13 SOURCE_VERSION=@SOURCE_VERSION@
14 OFFICIAL_BUILD=@OFFICIAL_BUILD@
16 # Use special abnormal exit codes so that problems with this library are more
17 # easily tracked down.
18 SHELL_LIB_INTERNAL_ERROR=86
19 SHELL_LIB_THROWN_ERROR=74
20 SHELL_LIB_USAGE_ERROR=99
22 # old -> new variable names
23 if [ -z "$DEBUG_XORG_PACKAGE" ] && [ -n "$DEBUG_XFREE86_PACKAGE" ]; then
24 DEBUG_XORG_PACKAGE="$DEBUG_XFREE86_PACKAGE"
26 if [ -z "$DEBUG_XORG_DEBCONF" ] && [ -n "$DEBUG_XFREE86_DEBCONF" ]; then
27 DEBUG_XORG_DEBCONF="$DEBUG_XFREE86_DEBCONF"
30 # initial sanity checks
31 if [ -z "$THIS_PACKAGE" ]; then
33 Error: package maintainer script attempted to use shell library without
34 definining \$THIS_PACKAGE shell variable. Please report the package name,
35 version, and the text of this error message to the Debian Bug Tracking System.
36 Visit <http://www.debian.org/Bugs/Reporting> on the World Wide Web for
37 instructions, read the file /usr/share/doc/debian/bug-reporting.txt from the
38 "doc-debian" package, or install the "reportbug" package and use the command of
39 the same name to file a report against version $SOURCE_VERSION of this package.
41 exit $SHELL_LIB_USAGE_ERROR
44 if [ -z "$THIS_SCRIPT" ]; then
46 Error: package maintainer script attempted to use shell library without
47 definining \$THIS_SCRIPT shell variable. Please report the package name,
48 version, and the text of this error message to the Debian Bug Tracking System.
49 Visit <http://www.debian.org/Bugs/Reporting> on the World Wide Web for
50 instructions, read the file /usr/share/doc/debian/bug-reporting.txt from the
51 "doc-debian" package, or install the "reportbug" package and use the command of
52 the same name to file a report against version $SOURCE_VERSION of the
53 "$THIS_PACKAGE" package.
55 exit $SHELL_LIB_USAGE_ERROR
58 if [ "$1" = "reconfigure" ] || [ -n "$DEBCONF_RECONFIGURE" ]; then
64 if ([ "$1" = "install" ] || [ "$1" = "configure" ]) && [ -z "$2" ]; then
68 if [ -z "$RECONFIGURE" ] && [ -z "$FIRSTINST" ]; then
73 message \"Received signal. Aborting $THIS_PACKAGE package $THIS_SCRIPT script.\";\
75 exit 1" HUP INT QUIT TERM
78 # syntax: reject_nondigits [ operand ... ]
80 # scan operands (typically shell variables whose values cannot be trusted) for
81 # characters other than decimal digits and barf if any are found
83 # does the operand contain anything but digits?
84 if ! expr "$1" : "[[:digit:]]\+$" > /dev/null 2>&1; then
85 # can't use die(), because it wraps message() which wraps this function
86 echo "$THIS_PACKAGE $THIS_SCRIPT error: reject_nondigits() encountered" \
87 "possibly malicious garbage \"$1\"" >&2
88 exit $SHELL_LIB_THROWN_ERROR
94 reject_unlikely_path_chars () {
95 # syntax: reject_unlikely_path_chars [ operand ... ]
97 # scan operands (typically shell variables whose values cannot be trusted) for
98 # characters unlikely to be seen in a path and which the shell might
99 # interpret and barf if any are found
100 while [ -n "$1" ]; do
101 # does the operand contain any funny characters?
102 if expr "$1" : '.*[!$&()*;<>?|].*' > /dev/null 2>&1; then
103 # can't use die(), because I want to avoid forward references
104 echo "$THIS_PACKAGE $THIS_SCRIPT error: reject_unlikely_path_chars()" \
105 "encountered possibly malicious garbage \"$1\"" >&2
106 exit $SHELL_LIB_THROWN_ERROR
112 # Query the terminal to establish a default number of columns to use for
113 # displaying messages to the user. This is used only as a fallback in the
114 # event the COLUMNS variable is not set. ($COLUMNS can react to SIGWINCH while
115 # the script is running, and this cannot, only being calculated once.)
116 DEFCOLUMNS=$(stty size 2> /dev/null | awk '{print $2}') || true
117 if ! expr "$DEFCOLUMNS" : "[[:digit:]]\+$" > /dev/null 2>&1; then
122 # pretty-print messages of arbitrary length
123 reject_nondigits "$COLUMNS"
124 echo "$*" | fmt -t -w ${COLUMNS:-$DEFCOLUMNS} >&2
128 # syntax: observe message ...
130 # issue observational message suitable for logging someday when support for
132 if [ -n "$DEBUG_XORG_PACKAGE" ]; then
133 message "$THIS_PACKAGE $THIS_SCRIPT note: $*"
138 # syntax: warn message ...
140 # issue warning message suitable for logging someday when support for
141 # it exists in dpkg; also send to standard error
142 message "$THIS_PACKAGE $THIS_SCRIPT warning: $*"
146 # syntax: die message ...
148 # exit script with error message
149 message "$THIS_PACKAGE $THIS_SCRIPT error: $*"
150 exit $SHELL_LIB_THROWN_ERROR
154 # exit script with error; essentially a "THIS SHOULD NEVER HAPPEN" message
155 message "internal error: $*"
156 if [ -n "$OFFICIAL_BUILD" ]; then
157 message "Please report a bug in the $THIS_SCRIPT script of the" \
158 "$THIS_PACKAGE package, version $SOURCE_VERSION to the Debian Bug" \
159 "Tracking System. Include all messages above that mention the" \
160 "$THIS_PACKAGE package. Visit " \
161 "<http://www.debian.org/Bugs/Reporting> on the World Wide Web for" \
162 "instructions, read the file" \
163 "/usr/share/doc/debian/bug-reporting.txt from the doc-debian" \
164 "package, or install the reportbug package and use the command of" \
165 "the same name to file a report."
167 exit $SHELL_LIB_INTERNAL_ERROR
171 message "usage error: $*"
172 message "Please report a bug in the $THIS_SCRIPT script of the" \
173 "$THIS_PACKAGE package, version $SOURCE_VERSION to the Debian Bug" \
174 "Tracking System. Include all messages above that mention the" \
175 "$THIS_PACKAGE package. Visit " \
176 "<http://www.debian.org/Bugs/Reporting> on the World Wide Web for" \
177 "instructions, read the file" \
178 "/usr/share/doc/debian/bug-reporting.txt from the doc-debian" \
179 "package, or install the reportbug package and use the command of" \
180 "the same name to file a report."
181 exit $SHELL_LIB_USAGE_ERROR
185 # run $UPDATECMDS in $FONTDIRS
187 local dir cmd shortcmd x_font_dir_prefix
189 x_font_dir_prefix="/usr/share/fonts/X11"
191 if [ -z "$UPDATECMDS" ]; then
192 usage_error "font_update() called but \$UPDATECMDS not set"
194 if [ -z "$FONTDIRS" ]; then
195 usage_error "font_update() called but \$FONTDIRS not set"
198 reject_unlikely_path_chars "$UPDATECMDS"
199 reject_unlikely_path_chars "$FONTDIRS"
201 for dir in $FONTDIRS; do
202 if [ -d "$x_font_dir_prefix/$dir" ]; then
203 for cmd in $UPDATECMDS; do
204 if which "$cmd" > /dev/null 2>&1; then
206 observe "running $shortcmd in $dir font directory"
208 if [ "$shortcmd" = "update-fonts-alias" ]; then
209 cmd_opts=--x11r7-layout
211 if [ "$shortcmd" = "update-fonts-dir" ]; then
212 cmd_opts=--x11r7-layout
214 if [ "$shortcmd" = "update-fonts-scale" ]; then
215 cmd_opts=--x11r7-layout
217 $cmd $cmd_opts $dir || warn "$cmd $cmd_opts $dir" \
218 "failed; font directory data may not" \
221 warn "$cmd not found; not updating corresponding $dir font" \
226 warn "$dir is not a directory; not updating font directory data"
231 remove_conffile_prepare () {
232 # syntax: remove_conffile_prepare filename official_md5sum ...
234 # Check a conffile "filename" against a list of canonical MD5 checksums.
235 # If the file's current MD5 checksum matches one of the "official_md5sum"
236 # operands provided, then prepare the conffile for removal from the system.
237 # We defer actual deletion until the package is configured so that we can
238 # roll this operation back if package installation fails.
240 # Call this function from a preinst script in the event $1 is "upgrade" or
241 # "install" and verify $2 to ensure the package is being upgraded from a
242 # version (or installed over a version removed-but-not-purged) prior to the
243 # one in which the conffile was obsoleted.
245 local conffile current_checksum
248 if [ $# -lt 2 ]; then
249 usage_error "remove_conffile_prepare() called with wrong number of" \
250 "arguments; expected at least 2, got $#"
251 exit $SHELL_LIB_USAGE_ERROR
257 # does the conffile even exist?
258 if [ -e "$conffile" ]; then
259 # calculate its checksum
260 current_checksum=$(md5sum < "$conffile" | sed 's/[[:space:]].*//')
261 # compare it to each supplied checksum
262 while [ -n "$1" ]; do
263 if [ "$current_checksum" = "$1" ]; then
264 # we found a match; move the confffile and stop looking
265 observe "preparing obsolete conffile $conffile for removal"
266 mv "$conffile" "$conffile.$THIS_PACKAGE-tmp"
274 remove_conffile_lookup () {
275 # syntax: remove_conffile_lookup package filename
277 # Lookup the md5sum of a conffile in dpkg's database, and prepare for removal
278 # if it matches the actual file's md5sum.
280 # Call this function when you would call remove_conffile_prepare but only
281 # want to check against dpkg's status database instead of known checksums.
283 local package conffile old_md5sum
286 if [ $# -ne 2 ]; then
287 usage_error "remove_conffile_lookup() called with wrong number of" \
288 "arguments; expected 1, got $#"
289 exit $SHELL_LIB_USAGE_ERROR
295 if ! [ -e "$conffile" ]; then
298 old_md5sum="$(dpkg-query -W -f='${Conffiles}' "$package" | \
299 awk '{ if (match($0, "^ '"$conffile"' ")) print $2}')"
300 if [ -n "$old_md5sum" ]; then
301 remove_conffile_prepare "$conffile" "$old_md5sum"
305 remove_conffile_commit () {
306 # syntax: remove_conffile_commit filename
308 # Complete the removal of a conffile "filename" that has become obsolete.
310 # Call this function from a postinst script after having used
311 # remove_conffile_prepare() in the preinst.
316 if [ $# -ne 1 ]; then
317 usage_error "remove_conffile_commit() called with wrong number of" \
318 "arguments; expected 1, got $#"
319 exit $SHELL_LIB_USAGE_ERROR
324 # if the temporary file created by remove_conffile_prepare() exists, remove it
325 if [ -e "$conffile.$THIS_PACKAGE-tmp" ]; then
326 observe "committing removal of obsolete conffile $conffile"
327 rm "$conffile.$THIS_PACKAGE-tmp"
331 remove_conffile_rollback () {
332 # syntax: remove_conffile_rollback filename
334 # Roll back the removal of a conffile "filename".
336 # Call this function from a postrm script in the event $1 is "abort-upgrade"
337 # or "abort-install" is after having used remove_conffile_prepare() in the
343 if [ $# -ne 1 ]; then
344 usage_error "remove_conffile_rollback() called with wrong number of" \
345 "arguments; expected 1, got $#"
346 exit $SHELL_LIB_USAGE_ERROR
351 # if the temporary file created by remove_conffile_prepare() exists, move it
353 if [ -e "$conffile.$THIS_PACKAGE-tmp" ]; then
354 observe "rolling back removal of obsolete conffile $conffile"
355 mv "$conffile.$THIS_PACKAGE-tmp" "$conffile"
359 replace_conffile_with_symlink_prepare () {
360 # syntax: replace_conffile_with_symlink_prepare oldfilename newfilename \
361 # official_md5sum ...
363 # Check a conffile "oldfilename" against a list of canonical MD5 checksums.
364 # If the file's current MD5 checksum matches one of the "official_md5sum"
365 # operands provided, then prepare the conffile for removal from the system.
366 # We defer actual deletion until the package is configured so that we can
367 # roll this operation back if package installation fails. Otherwise copy it
368 # to newfilename and let dpkg handle it through conffiles mechanism.
370 # Call this function from a preinst script in the event $1 is "upgrade" or
371 # "install" and verify $2 to ensure the package is being upgraded from a
372 # version (or installed over a version removed-but-not-purged) prior to the
373 # one in which the conffile was obsoleted.
375 local conffile current_checksum
378 if [ $# -lt 3 ]; then
379 usage_error "replace_conffile_with_symlink_prepare() called with wrong" \
380 " number of arguments; expected at least 3, got $#"
381 exit $SHELL_LIB_USAGE_ERROR
389 remove_conffile_prepare "$_oldconffile" "$@"
390 # If $oldconffile still exists, then md5sums didn't match.
391 # Copy it to new one.
392 if [ -f "$oldconffile" ]; then
393 cp "$oldconffile" "$newconffile"
398 replace_conffile_with_symlink_commit () {
399 # syntax: replace_conffile_with_symlink_commit oldfilename
401 # Complete the removal of a conffile "oldfilename" that has been
402 # replaced by a symlink.
404 # Call this function from a postinst script after having used
405 # replace_conffile_with_symlink_prepare() in the preinst.
410 if [ $# -ne 1 ]; then
411 usage_error "replace_conffile_with_symlink_commit() called with wrong" \
412 "number of arguments; expected 1, got $#"
413 exit $SHELL_LIB_USAGE_ERROR
418 remove_conffile_commit "$conffile"
421 replace_conffile_with_symlink_rollback () {
422 # syntax: replace_conffile_with_symlink_rollback oldfilename newfilename
424 # Roll back the replacing of a conffile "oldfilename" with symlink to
427 # Call this function from a postrm script in the event $1 is "abort-upgrade"
428 # or "abort-install" and verify $2 to ensure the package failed to upgrade
429 # from a version (or install over a version removed-but-not-purged) prior
430 # to the one in which the conffile was obsoleted.
431 # You should have used replace_conffile_with_symlink_prepare() in the
437 if [ $# -ne 2 ]; then
438 usage_error "replace_conffile_with_symlink_rollback() called with wrong" \
439 "number of arguments; expected 2, got $#"
440 exit $SHELL_LIB_USAGE_ERROR
446 remove_conffile_rollback "$_oldconffile"
447 if [ -f "$newconffile" ]; then
453 # syntax: run command [ argument ... ]
455 # Run specified command with optional arguments and report its exit status.
456 # Useful for commands whose exit status may be nonzero, but still acceptable,
457 # or commands whose failure is not fatal to us.
459 # NOTE: Do *not* use this function with db_get or db_metaget commands; in
460 # those cases the return value of the debconf command *must* be checked
461 # before the string returned by debconf is used for anything.
466 if [ $# -lt 1 ]; then
467 usage_error "run() called with wrong number of arguments; expected at" \
469 exit $SHELL_LIB_USAGE_ERROR
474 if [ ${retval:-0} -ne 0 ]; then
475 observe "command \"$*\" exited with status $retval"
479 make_symlink_sane () {
480 # syntax: make_symlink_sane symlink target
482 # Ensure that the symbolic link symlink exists, and points to target.
484 # If symlink does not exist, create it and point it at target.
486 # If symlink exists but is not a symbolic link, back it up.
488 # If symlink exists, is a symbolic link, but points to the wrong location, fix
491 # If symlink exists, is a symbolic link, and already points to target, do
494 # This function wouldn't be needed if ln had an -I, --idempotent option.
496 # Validate arguments.
497 if [ $# -ne 2 ]; then
498 usage_error "make_symlink_sane() called with wrong number of arguments;" \
500 exit $SHELL_LIB_USAGE_ERROR
503 # We could just use the positional parameters as-is, but that makes things
510 if [ -L "$symlink" ] && [ "$(readlink "$symlink")" = "$target" ]; then
511 observe "link from $symlink to $target already exists"
513 observe "creating symbolic link from $symlink to $target"
514 mkdir -p "${target%/*}" "${symlink%/*}"
515 ln -s -b -S ".dpkg-old" "$target" "$symlink"
519 migrate_dir_to_symlink () {
520 # syntax: migrate_dir_to_symlink old_location new_location
522 # Per Debian Policy section 6.5.4, "A directory will never be replaced by a
523 # symbolic link to a directory or vice versa; instead, the existing state
524 # (symlink or not) will be left alone and dpkg will follow the symlink if
527 # We have to do it ourselves.
529 # This function moves the contents of old_location, a directory, into
530 # new_location, a directory, then makes old_location a symbolic link to
533 # old_location need not exist, but if it does, it must be a directory (or a
534 # symlink to a directory). If it is not, it is backed up. If new_location
535 # exists already and is not a directory, it is backed up.
537 # This function should be called from a package's preinst so that other
538 # packages unpacked after this one --- but before this package's postinst runs
539 # --- are unpacked into new_location even if their payloads contain
540 # old_location filespecs.
542 # Validate arguments.
543 if [ $# -ne 2 ]; then
544 usage_error "migrate_dir_to_symlink() called with wrong number of"
545 "arguments; expected 2, got $#"
546 exit $SHELL_LIB_USAGE_ERROR
549 # We could just use the positional parameters as-is, but that makes things
556 # Is old location a symlink?
557 if [ -L "$old" ]; then
558 # Does it already point to new location?
559 if [ "$(readlink "$old")" = "$new" ]; then
560 # Nothing to do; migration has already been done.
561 observe "migration of $old to $new already done"
565 warn "backing up symbolic link $old as $old.dpkg-old"
566 mv -b "$old" "$old.dpkg-old"
570 # Does old location exist, but is not a directory?
571 if [ -e "$old" ] && ! [ -d "$old" ]; then
573 warn "backing up non-directory $old as $old.dpkg-old"
574 mv -b "$old" "$old.dpkg-old"
577 observe "migrating $old to $new"
579 # Is new location a symlink?
580 if [ -L "$new" ]; then
581 # Does it point the wrong way, i.e., back to where we're migrating from?
582 if [ "$(readlink "$new")" = "$old" ]; then
584 observe "removing symbolic link $new which points to $old"
588 warn "backing up symbolic link $new as $new.dpkg-old"
589 mv -b "$new" "$new.dpkg-old"
593 # Does new location exist, but is not a directory?
594 if [ -e "$new" ] && ! [ -d "$new" ]; then
595 warn "backing up non-directory $new as $new.dpkg-old"
596 mv -b "$new" "$new.dpkg-old"
599 # Create new directory if it does not yet exist.
600 if ! [ -e "$new" ]; then
601 observe "creating $new"
605 # Copy files in old location to new location. Back up any filenames that
606 # already exist in the new location with the extension ".dpkg-old".
607 observe "copying files from $old to $new"
608 if ! (cd "$old" && cp -a -b -S ".dpkg-old" . "$new"); then
609 die "error(s) encountered while copying files from $old to $new"
612 # Remove files at old location.
613 observe "removing $old"
616 # Create symlink from old location to new location.
617 make_symlink_sane "$old" "$new"
620 # vim:set ai et sw=2 ts=2 tw=80:
622 # GOBSTOPPER: The X Strike Force shell library ends here.