Bootloader::Core.3pm

Langue: en

Version: 2007-09-26 (openSuse - 09/10/07)

Section: 3 (Bibliothèques de fonctions)

NAME

Bootloader::Core - core library for bootloader configuration

PREFACE

This package is the core library of the bootloader configuration

SYNOPSIS

use Bootloader::Core;

"$mountpoint = Bootloader::Core->Dev2MP ($device);"

"$device = Bootloader::Core->MP2Dev ($mountpoint);"

"$members_ref = Bootloader::Core->MD2Members ($md_device);"

"$md_dev = Bootloader::Core->Member2MD (string $md_member);"

"$index = Bootloader::Core->IndexOfSection ($name, \@section_names);"

"($device, $path) = Bootloader::Core->SplitDevPath ($path);"

"$quoted = Bootloader::Core->Quote ($text, $when);"

"$unquoted = Bootloader::Core->Unquote ($text);"

"$section_ref = Bootloader::Core->FixSectionLineOrder (\@section_ref, \@preferred);"

"$sections_ref Bootloader::Core->SplitLinesToSections (\@lines, \@section_starts);"

"$lines_ref Bootloader::Core->MergeSectionsLines (\@sections, $indent);"

"$lines_ref Bootloader::Core->ProcessMenuFileLines (\@lines, $separator);"

"$line_empty = Bootloader::Core->MenuFileLineEmpty ($line);"

"($lines_ref, $com_bef) Bootloader::Core->ProcessSingleMenuFileLine ($lines, $com_bef, $separator);"

"$lines_ref = Bootloader::Core->CreateMenuFileLines (\@parsed_lines, $separator);"

"$line = Bootloader::Core->CreateSingleMenuFileLine ($key, $value, $separator);"

"$empty = Bootloader::Core->HasEmptyValue ($key, $value);"

"$obj_ref = Bootloader::Core->new ();"

"files_list_ref = Bootloader::Core->ListMenuFiles ();"

"$files_ref = Bootloader::Core->ReadFiles (\@file_names);"

"$status = Bootloader::Core->WriteFiles (\%files, $suffix);"

"$original_name = Bootloader::Core->Comment2OriginalName ($comment);"

"$line_ref = Bootloader::Core->UpdateSectionNameLine ($name, \%line, $original_name);"

"$original_name = Bootloader::Core->Comment2FormerFlavor ($comment);"

"$line_ref = Bootloader::Core->CreateFormerDefaultImageLine (\%line, $former_flavor);"

"$sectin_info_ref = Bootloader::Core->Section2Info (\@section_lines);"

"$label = Bootloader::Core->FixSectionName ($name, \@existing, $orig_name);"

"$lines_ref = Bootloader::Core->Info2Section (\%section_info, @section_names);"

"$glob_info = $Bootloader::Core->Global2Info (\@glob_lines, \@section_names);"

"$lines_ref = Bootloader::Core->Info2Global (\%section_info, \@section_names);"

"$sections_ref = Bootloader::Core->MarkInitialSection (\@sections, default);"

"($global_ref, $sections_ref) Bootloader::Core->ParseMenuFileLines ($separator, \@start_keys, \@lines);"

"$lines_ref = Bootloader::Core->PrepareMenuFileLines (\@sectinos, \%global, $indent, $separator);"

"$status = Bootloader::Core->UpdateBootloader ();"

"$status = Bootloader::Core->RunCommand ($command, $log_file);"

"$mapping_ref = Bootloader::Core->GetDeviceMapping ();"

"$status = Bootloader::Core->SetDeviceMapping (\%mapping_ref);"

"$settings_ref = Bootloader::Core->GetSettings ();"

"$status = Bootloader::Core->SetSettings (\%settings);"

"$path = Bootloader::Core->ConcatPath ($path1, $path2);"

"$crosses = Bootloader::Core->SymlinkCrossesDevice ($path);"

"$resolved = Bootloader::Core->ResolveCrossDeviceSymlinks ($path);"

"$canonical = Bootloader::Core->CanonicalPath ($path);"

"$real = Bootloader::Core->RealFileName ($filename);"

"Bootloader::Core->l_debug ($message);"

"Bootloader::Core->l_milestone ($message);"

"Bootloader::Core->l_warning ($message);"

"Bootloader::Core->l_error ($message);"

"$records_ref = Bootloader::Core->GetLogRecords ();"

"Bootloader::Core->MangleSections (\@sections, \%global);"

DESCRIPTION

*
"Bootloader::Core->l_debug ($message);"

Writes a debug message to the system log buffer.

*
"Bootloader::Core->l_milestone ($message);"

Writes a milestone message to the system log buffer.

*
"Bootloader::Core->l_warning ($message);"

Writes a warning message to the system log buffer.

*
"Bootloader::Core->l_error ($message);"

Writes an error message to the system log buffer.

*
"$records_ref = Bootloader::Core->GetLogRecords ();"
$mountpoint = Bootloader::Core->Dev2MP ($device);
Gets the mount point where a specified device is mounted. As argument takes the device to examinate (string, eg. '/dev/hda1'), returns the mountopint where the device is mounter (string, eg. '/boot'), or undef if the device is not mounted (according to /etc/fstab).
$device = Bootloader::Core->MP2Dev ($mountpoint);
Gets the device where filesystem mounted at a specified mountpoint is located. As argument takes the mount point (string, eg. '/boot'), returns the device (string, eg. '/dev/hda1'), or undef if there is no device mounted in the specified directory
$members_ref = Bootloader::Core->MD2Members ($md_device);
Gets the list of partitions building an MD software RAID array. As argument it takes a MD device (string), returns a reference to a list of its members.
$md_dev = Bootloader::Core->Member2MD (string $md_member);
Gets the MD RAID device a specified disk belongs to. As argument, it takes a disk which is supposed to be a member of a RAID, returns the RAID device name.
$index = Bootloader::Core->IndexOfSection ($name, \@section_names);
Finds the section in the list. As arguments, takes the name of the section (string, eg. 'linux') and the list of section names (list reference, eg. "['linux', 'failsafe']"). Returns index of the section (integer) or undef if the section was not found in the list.
($device, $path) = Bootloader::Core->SplitDevPath ($path);
Divides the absolute path to the mountpoint and path relative to the mountpoint, transforms the mountpoint to the device holding the filesystem. As argument it takes the path (string, eg. '/boot/grub/device.map'), returns two-entry-list (NOT a reference) containing the device and the relative path (eg. "('/dev/hda1', '/grub/device.map')")
$extended_part_dev = Bootloader::Core->GetExtendedPartition ($part_dev);
Takes a device name (string, eg. '/dev/sda7') and returns the device name of the extended partition on the same disk (string, eg. '/dev/sda3'). If no extended partition exists on that disk, returns undef.
$quoted = Bootloader::Core->Quote ($text, $when);
Puts a text to quotes. As arguments takes the text (string) and information when the text should be put into quotes (string, 'always' or 'blanks' to specify if the text should be put between quotes always or only if it contains at least one blank character. Returns the text put into the quotes (if wanted or needed) (string)
$unquoted = Bootloader::Core->Unquote ($text);
Removes leading and tailing quotes of a string. As argument takes a string, returns it unquoted.
$merged = Bootloader::Core->MergeDefined (@strings);
Merges the strings (those defined and non-empty). As arguments, it takes strings, returns them merged with one space character.
$section_ref = Bootloader::Core->FixSectionLineOrder (\@section_ref, \@preferred);
reorders the lines of the section. As arguments takes reference to lines of the section (each line represented as a hash reference), and a list of preferred keys. Returns a reference to the reordered lines of a section. Lines having any of the preferred keys will be in the return value placed before the other ones. If there are multiple lines having a preferred key, they will be sorted according to the list of oreferred keys.
$sections_ref Bootloader::Core->SplitLinesToSections (\@lines, \@section_starts);
Splits the lines of the configuration file to particular sections As argument it takes a reference to a list of lines (each line represented as a hash) and a reference to a list of keys starting a new section. Returns a reference of a list of sections, each represented as a list of lines. The first section is the global section of the bootloader (without
$lines_ref Bootloader::Core->MergeSectionsLines (\@sections, $indent);
merges the sections into one. Except all lines of the first section and the first lines of other sections, all lines are indented by the specified string. As arguments takes a list of sections (global section should be at the beginning of the list) and a string specifying the indentation. Returns a list of lines. Each section is represented as a list of lines, line is represented as a hash.
$lines_ref Bootloader::Core->ProcessMenuFileLines (\@lines, $separator);
processes lines represented as strings and returns them represented as hashes (containing key, value, relevant comments). As argument, it takes a reference to the list of lines of the file containing the menu and separator between the key and value. Returns a reference to a list of hashed.
$line_empty = Bootloader::Core->MenuFileLineEmpty ($line);
checks if a line is empty (or contains the time stamp by the library), or contains some information (comment is treated as information here). Takes the line as string, returns a scalar (1 if empty, 0 otherwise).
($lines_ref, $com_bef) Bootloader::Core->ProcessSingleMenuFileLine ($lines, $com_bef, $separator);
processes line represented as string and returns it represented as hashes (containing key, value, relevant comments). The list may be empty, contain one or more items. As argument, it takes a line (as string), comment from previous lines and separator between the key and value. Returns a reference to a list of hashed and a pending comment.
$lines_ref = Bootloader::Core->CreateMenuFileLines (\@parsed_lines, $separator);
Transforms the list of lines (hashes) to list of lines-string to save. As arguments it takes the list of lines represented as hashes and a string to separate the key ent the value. Returns a reference to a list of strings.
$line = Bootloader::Core->CreateSingleMenuFileLine ($key, $value, $separator);
Transforms a line (hash) to a string to save. As arguments it takes the the key, the value and a string to separate the key and the value. Returns a string.
$empty = Bootloader::Core->HasEmptyValue ($key, $value);
Checks if a value is empty and only the keyword is to be written to the configuration file. Takes the key and value, returns if only keyword is to be written to configuration file
$obj_ref = Bootloader::Core->new ($old);
Creates an instance of the Bootloader::Core class. Optional parameter 'old' is object reference to former bootloader =cut sub new {
    my $self = shift;
    my $old = shift;

    my $loader = {};

    # keep old settings if given as parameter

    if (defined($old)) {

        foreach my $key (keys %{$old}) {

            $loader->{$key} = $old->{$key};

        }

    }

    $loader->{"log_records"} = [];




    bless ($loader);

    return $loader;

}



# list<string> ListFiles (); # must be overridden sub ListFiles {
    my $self = shift;
    $self->l_error (``Bootloader::Core::ListFiles: Running generic function, it should never be called'');
    return []; }

files_list_ref = Bootloader::Core->ListMenuFiles ();
List configuration files which have to be changed if only the boot menu has changed.
$files_ref = Bootloader::Core->ReadFiles (\@file_names);
Actually reads the files from the disk. As argument, takes a reference to the list of file names, returns a hash, where key is file name and value a reference to the list of lines of the file.
$status = Bootloader::Core->WriteFiles (\%files, $suffix, $menu_only);
Writes the files to the disk. As arguments, it takes a reference to a hash, where key is file name and value a reference to the list of lines to write to the file, and a suffix. Does not write the contents directly to the files, but $suffix is appended to the file names. On success, returns defined value > 0, on fail, returns undef;
$original_name = Bootloader::Core->Comment2OriginalName ($comment);
Gets the original name of the section from the comment. As argument, takes the comment, returns the original name (if found in the comment), or empty string (otherwise).
$line_ref = Bootloader::Core->UpdateSectionNameLine ($name, \%line, $original_name);
Updates the 'section name line' so that it contains specified name and original name inside the comment. As arguments, takes the name (string), the line (hash reference) and the original name (string). If original name is set to undef or empty string, it is not set in the comment. Returns the updated line reference.
$original_name = Bootloader::Core->Comment2FormerFlavor ($comment);
Gets the flavor of the former default image from the comment. As argument, takes the comment, returns the former flavor (if found in the comment), or empty string (otherwise).
$line_ref = Bootloader::Core->CreateFormerDefaultImageLine (\%line, $former_flavor);
Updates the 'default line' in globals so that it contains the former default image flavor inside the comment. As arguments, takes the line (hash reference) and the former flavor (string). If former flavor is set to undef or empty string, it is not set in the comment. Returns the updated line reference.
$sectin_info_ref = Bootloader::Core->Section2Info (\@section_lines);
Gets the information about the section. As argument, takes a reference to the list of lines building the section, returns a reference to a hash containing information about the section.
*
"$label = Bootloader::Core->FixSectionName ($name, \@existing, $orig_name);"

Update the section name so that it does not break anything (is in compliance with the bootloader and is unique). As arguments takes suggested section name and list of existing sections, returns updated section name and updates the list of section names as a side effect. Optional parameter orig_name is intended for internal use of the loader specific modules

$lines_ref = Bootloader::Core->Info2Section (\%section_info, \@section_names);
Takes the info about the section and uses it to construct the list of lines. The info about the section also contains the original lines. As parameter, takes the section info (reference to a hash), returns the lines (a list of hashes). =cut

# list<map<string,any>> Info2Section (map<string,string> info, list<string> section_names) sub Info2Section {
    my $self = shift;
    my %sectinfo = %{+shift};
    my $sect_names_ref = shift;


    my @lines = @{$sectinfo{"__lines"} || []};

    my $type = $sectinfo{"type"} || "";




    # allow to keep the section unchanged

    if (! ($sectinfo{"__modified"} || 0))

    {

        return $self->FixSectionLineOrder (

            \@lines,

            ["image", "other"]);

    }




    $sectinfo{"name"} = $self->FixSectionName ($sectinfo{"name"}, $sect_names_ref);




    @lines = map {

        my $line_ref = $_;

        my $key = $line_ref->{"key"};




        if ($key eq "label")

        {

            $line_ref = $self->UpdateSectionNameLine ($sectinfo{"name"}, $line_ref, $sectinfo{"original_name"});

            delete ($sectinfo{"name"});

        }

        elsif ($key eq "image" || $key eq "initrd" || $key eq "root"

            || $key eq "vga" || $key eq "append" || $key eq "wildcard")

        {

            $key = "kernel" if ($key eq "image");

            if ($type eq "chainloader" || ! defined ($sectinfo{$key}))

            {

                $line_ref = undef;

            }

            else

            {

                $line_ref->{"value"} = $sectinfo{$key};

                delete ($sectinfo{$key});

            }

        }

        elsif ($key eq "other")

        {

            if ($type eq "image" || ! defined ($sectinfo{$key}))

            {

                $line_ref = undef;

            }

            else

            {

                $line_ref->{"value"} = $sectinfo{$key};

                delete ($sectinfo{$key});

            }

        }




        $line_ref;

    } @lines;




    @lines = grep {

        defined $_;

    } @lines;




    while ((my $key, my $value) = each (%sectinfo))

    {

        if ($key eq "name")

        {

            my $line_ref = $self->UpdateSectionNameLine ($sectinfo{"name"}, {}, $sectinfo{"original_name"});

            $line_ref->{"key"} = "label";

            push @lines, $line_ref;

        }

        elsif ($key eq "kernel" || $key eq "initrd" || $key eq "root"

            || $key eq "vga" || $key eq "append" || $key eq "chainloader"

            || $key eq "wildcard" || $key eq "image" || $key eq "other")

        {

            $key = "image" if ($key eq "kernel");

            $key = "other" if ($key eq "chainloader");

            push @lines, {

                "key" => $key,

                "value" => $value,

            };

        }

    }




    my $ret = $self->FixSectionLineOrder (\@lines,

        ["image", "other"]);




    return $ret;

}



$glob_info = $Bootloader::Core->Global2Info (\@glob_lines, \@section_names);
Gets the general information from the global section of the menu file. This information usually means the default section, graphical menu, timeout etc. As argument it takes a reference to the list of hashes representing lines of the section, returns a reference to a hash containing the important information.
$lines_ref = Bootloader::Core->Info2Global (\%section_info, \@section_names);
Takes the info about the global options and uses it to construct the list of lines. The info about global option also contains the original lines. As parameter, takes the section info (reference to a hash) and a list of sectino names, returns the lines (a list of hashes).
$sections_ref = Bootloader::Core->MarkInitialSection (\@sections, default);
Marks the section that is the initial one - the ``Linux'' section (even if it had been renamed). Uses several heuristics to get this one, one of them is the default section name. As arguments, takes the list of all sections and the default section name. Returns the list of sections, where the default one has the ``initial'' key set.
($global_ref, $sections_ref) Bootloader::Core->ParseMenuFileLines ($separator, \@start_keys, \@lines);
Parses the lines of the file containing the bootloader menu, and creates the hashes representing the global settings and the sections. As arguments takes the separator of the key and value in the file, reference to a list starting a new section, and reference to the list of lines. Returns reference to a hash representing global options and reference to a list representing all sections.
$lines_ref = Bootloader::Core->PrepareMenuFileLines (\@sectinos, \%global, $indent, $separator);
takes the information about sections and creates the list of lines to be written to the file holding the boot menu. As arguments, takes reference to the list of sections, reference to hash holding global options, indentation of the lines inside sections and separator to be used between key and value in the configuration file. Returns the list of lines to be written to the configuration file.
$status = Bootloader::Core->UpdateBootloader ();
Updates the settings in the system. Backs original configuration files up and replaces them with the ones with the '.new' suffix. If other operations are needed to make the change effect, they must be done in the loader-specific package (eg. not needed for GRUB, run '/sbin/lilo' for LILO). Returns undef on fail, defined nonzero value on success.
$status = Bootloader::Core->RunCommand ($command, $log_file);
Runs specified command. If log file is defined, its stdout and stderr are appended to the log file. As arguments, takes the command end the log file name. Returns exit code of the command.
$mapping_ref = Bootloader::Core->GetDeviceMapping ();
Returns the device mapping as a reference to a hash, where key is the UNIX device identification and value is the firmware device identification.
$status = Bootloader::Core->SetDeviceMapping (\%mapping_ref);
Sets the device mapping. As argument takes a hash reference, where key is UNIX device identificatino and value is the firmware devide identification. Returns undef on fail, defined nonzero value otherwise.
$settings_ref = Bootloader::Core->GetSettings ();
returns the complete settings in a hash. Does not read the settings from the system, but returns internal structures.
$status = Bootloader::Core->SetSettings (\%settings);
Stores the settings in the given parameter to the internal structures. Does not touch the system. Returns undef on fail, defined nonzero value on success.
$path = Bootloader::Core->ConcatPath ($path1, $path2);
Concatenates two path elements, added slash inbeteween if needed. Returns the two elements (arguments) concatenated.
$crosses = Bootloader::Core->SymlinkCrossesDevice ($path);
Checks if specified path is a symlink and if it links to path on a different device. As argument takes a path, returns 1 if path is a symlink and crosses device, 0 otherwise.
*
"$resolved = Bootloader::Core->ResolveCrossDeviceSymlinks ($path);"

Resolves all symlinks crossing device in the path. As argument, takes a path possibly with symlinks crossing device, returns the same path with these symlinks resolved.

*
"$canonical = Bootloader::Core->CanonicalPath ($path);"

Makes a ``beautification'' of the path given as an argument, returns the path.

*
"$real = Bootloader::Core->RealFileName ($filename);"

Gets the file name with all symlinks resolved and with some ``beautification'' (eg. removing duplicate slashes). Takes one argument - path, returns it after symlniks resolved.

*
"Bootloader::Core->MangleSections (\@sections, \%global);"

In this version does not do anything, is needed just to be overridden by the ZIPL implementation where global stuff is in sections