From 7e2bca48208413b940ebdf875c718a0d08e490ac Mon Sep 17 00:00:00 2001

From: Harald Hoyer <harald@redhat.com>

Date: Thu, 16 Feb 2012 11:49:19 +0100

Subject: [PATCH] dracut-functions: documentation and restructuring

---

 dracut-functions |  157 ++++++++++++++++++++++++++++++++++++++++++------------

 1 files changed, 122 insertions(+), 35 deletions(-)

diff --git a/dracut-functions b/dracut-functions

index 0b24889..e0a08ab 100755

--- a/dracut-functions

+++ b/dracut-functions

@@ -32,6 +32,13 @@ if ! type dinfo >/dev/null 2>&1; then

     dlog_init

 fi

+# export standard hookdirs

+[[ $hookdirs ]] || {

+    hookdirs="cmdline pre-udev pre-trigger netroot initqueue pre-mount"

+    hookdirs+=" pre-pivot mount emergency shutdown-emergency shutdown cleanup"

+    export hookdirs

+}

+

 # Generic substring function.  If $2 is in $1, return 0.

 strstr() { [[ $1 =~ $2 ]]; }

@@ -66,6 +73,8 @@ vercmp() {

     esac

 }

+# is_func <command>

+# Check whether $1 is a function.

 is_func() {

     [[ $(type -t $1) = "function" ]]

 }

@@ -82,6 +91,12 @@ print_vars() {

     done

 }

+# normalize_path <path>

+# Prints the normalized path, where it removes any duplicated

+# and trailing slashes.

+# Example:

+# $ normalize_path ///test/test//

+# /test/test

 normalize_path() {

     shopt -q -s extglob

     set -- "${1//+(\/)//}"

@@ -89,10 +104,15 @@ normalize_path() {

     echo "${1%/}"

 }

+# convert_abs_rel <from> <to>

+# Prints the relative path, when creating a symlink to <to> from <from>.

+# Example:

+# $ convert_abs_rel /usr/bin/test /bin/test-2

+# ../../bin/test-2

+# $ ln -s $(convert_abs_rel /usr/bin/test /bin/test-2) /usr/bin/test

 convert_abs_rel() {

     local __current __absolute __abssize __cursize __newpath __oldifs

     local -i __i __level

-#    PS4='${BASH_SOURCE}@${LINENO}(${FUNCNAME[0]}): ';

     set -- "$(normalize_path "$1")" "$(normalize_path "$2")"

@@ -141,6 +161,12 @@ convert_abs_rel() {

     echo "$__newpath"

 }

+# get_fs_env <device>

+# Get and set the ID_FS_TYPE and ID_FS_UUID variable from udev for a device.

+# Example:

+# $ get_fs_env /dev/sda2; echo $ID_FS_TYPE; echo $ID_FS_UUID

+# ext4

+# 551a39aa-4ae9-4e70-a262-ef665cadb574

 get_fs_env() {

     [[ $1 ]] || return

     unset ID_FS_TYPE

@@ -157,6 +183,21 @@ get_fs_env() {

     fi

 }

+# get_fs_uuid <device>

+# Prints the filesystem UUID for a device.

+# Example:

+# $ get_fs_uuid /dev/sda2

+# 551a39aa-4ae9-4e70-a262-ef665cadb574

+get_fs_uuid() (

+    get_fs_env $1 || return

+    echo $ID_FS_UUID

+)

+

+# get_fs_type <device>

+# Prints the filesystem type for a device.

+# Example:

+# $ get_fs_type /dev/sda1

+# ext4

 get_fs_type() (

     [[ $1 ]] || return

     if [[ $1 != ${1#/dev/block/nfs:} ]] \

@@ -172,12 +213,11 @@ get_fs_type() (

     find_dev_fstype $1

 )

-get_fs_uuid() (

-    get_fs_env $1 || return

-    echo $ID_FS_UUID

-)

-

-

+# get_maj_min <device>

+# Prints the major and minor of a device node.

+# Example:

+# $ get_maj_min /dev/sda2

+# 8:2

 get_maj_min() {

     local _dev

     _dev=$(stat -L -c '$((0x%t)):$((0x%T))' "$1" 2>/dev/null)

@@ -185,6 +225,16 @@ get_maj_min() {

     echo $_dev

 }

+# find_block_device <mountpoint>

+# Prints the major and minor number of the block device

+# for a given mountpoint.

+# Unless $use_fstab is set to "yes" the functions

+# uses /proc/self/mountinfo as the primary source of the

+# information and only falls back to /etc/fstab, if the mountpoint

+# is not found there.

+# Example:

+# $ find_block_device /usr

+# 8:4

 find_block_device() {

     local _x _mpt _majmin _dev _fs _maj _min

     if [[ $use_fstab != yes ]]; then

@@ -219,6 +269,14 @@ find_block_device() {

     return 1

 }

+# find_dev_fstype <device>

+# Echo the filesystem type for a given device.

+# /proc/self/mountinfo is taken as the primary source of information

+# and /etc/fstab is used as a fallback.

+# No newline is appended!

+# Example:

+# $ find_dev_fstype /dev/sda2;echo

+# ext4

 find_dev_fstype() {

     local _x _mpt _majmin _dev _fs _maj _min

     while read _x _x _majmin _x _mpt _x _x _fs _dev _x; do

@@ -240,6 +298,9 @@ find_dev_fstype() {

 # finds the major:minor of the block device backing the root filesystem.

 find_root_block_device() { find_block_device /; }

+# for_each_host_dev_fs <func>

+# Execute "<func> <dev> <filesystem>" for every "<dev>|<fs>" pair found

+# in ${host_fs_types[@]}

 for_each_host_dev_fs()

 {

     local _func="$1"

@@ -581,12 +642,6 @@ inst() {

     return 1

 }

-[[ $hookdirs ]] || {

-    hookdirs="cmdline pre-udev pre-trigger netroot initqueue pre-mount"

-    hookdirs+=" pre-pivot mount emergency shutdown-emergency shutdown cleanup"

-    export hookdirs

-}

-

 # install function specialized for hooks

 # $1 = type of hook, $2 = hook priority (lower runs first), $3 = hook

 # All hooks should be POSIX/SuS compliant, they will be sourced by init.

@@ -630,6 +685,9 @@ inst_any() {

     return 1

 }

+# dracut_install [-o ] <file> [<file> ... ]

+# Install <file> to the initramfs image

+# -o optionally install the <file> and don't fail, if it is not there

 dracut_install() {

     local _optional=no

     if [[ $1 = '-o' ]]; then

@@ -697,6 +755,10 @@ inst_opt_decompress() {

     done

 }

+# module_check <dracut module>

+# execute the check() function of module-setup.sh of <dracut module>

+# or the "check" script, if module-setup.sh is not found

+# "check $hostonly" is called

 module_check() {

     local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

     local _ret

@@ -723,6 +785,35 @@ module_check() {

     return $_ret

 }

+# module_check_mount <dracut module>

+# execute the check() function of module-setup.sh of <dracut module>

+# or the "check" script, if module-setup.sh is not found

+# "mount_needs=1 check 0" is called

+module_check_mount() {

+    local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

+    local _ret

+    mount_needs=1

+    [[ -d $_moddir ]] || return 1

+    if [[ ! -f $_moddir/module-setup.sh ]]; then

+        # if we do not have a check script, we are unconditionally included

+        [[ -x $_moddir/check ]] || return 0

+        mount_needs=1 $_moddir/check 0

+        _ret=$?

+    else

+        unset check depends install installkernel

+        . $_moddir/module-setup.sh

+        is_func check || return 1

+        check 0

+        _ret=$?

+        unset check depends install installkernel

+    fi

+    unset mount_needs

+    return $_ret

+}

+

+# module_depends <dracut module>

+# execute the depends() function of module-setup.sh of <dracut module>

+# or the "depends" script, if module-setup.sh is not found

 module_depends() {

     local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

     local _ret

@@ -743,6 +834,9 @@ module_depends() {

     fi

 }

+# module_install <dracut module>

+# execute the install() function of module-setup.sh of <dracut module>

+# or the "install" script, if module-setup.sh is not found

 module_install() {

     local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

     local _ret

@@ -761,6 +855,9 @@ module_install() {

     fi

 }

+# module_installkernel <dracut module>

+# execute the installkernel() function of module-setup.sh of <dracut module>

+# or the "installkernel" script, if module-setup.sh is not found

 module_installkernel() {

     local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

     local _ret

@@ -779,28 +876,9 @@ module_installkernel() {

     fi

 }

-module_check_mount() {

-    local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

-    local _ret

-    mount_needs=1

-    [[ -d $_moddir ]] || return 1

-    if [[ ! -f $_moddir/module-setup.sh ]]; then

-        # if we do not have a check script, we are unconditionally included

-        [[ -x $_moddir/check ]] || return 0

-        mount_needs=1 $_moddir/check 0

-        _ret=$?

-    else

-        unset check depends install installkernel

-        . $_moddir/module-setup.sh

-        is_func check || return 1

-        check 0

-        _ret=$?

-        unset check depends install installkernel

-    fi

-    unset mount_needs

-    return $_ret

-}

-

+# check_mount <dracut module>

+# check_mount checks, if a dracut module is needed for the given

+# device and filesystem types in "${host_fs_types[@]}"

 check_mount() {

     local _mod=$1

     local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

@@ -840,6 +918,10 @@ check_mount() {

     return 0

 }

+# check_module <dracut module> [<use_as_dep>]

+# check if a dracut module is to be used in the initramfs process

+# if <use_as_dep> is set, then the process also keeps track

+# that the modules were checked for the dependency tracking process

 check_module() {

     local _mod=$1

     local _moddir=$(echo ${dracutbasedir}/modules.d/??${1})

@@ -891,6 +973,8 @@ check_module() {

     return 0

 }

+# for_each_module_dir <func>

+# execute "<func> <dracut module> 1"

 for_each_module_dir() {

     local _modcheck

     local _mod

@@ -1028,7 +1112,10 @@ find_kernel_modules () {

     find_kernel_modules_by_path  drivers

 }

+# instmods <kernel module> [<kernel module> ... ]

+# instmods <kernel subsystem>

 # install kernel modules along with all their dependencies.

+# <kernel subsystem> can be e.g. "=block" or "=drivers/usb/storage"

 instmods() {

     [[ $no_kernel = yes ]] && return

     # called [sub]functions inherit _fderr