/usr/share/doc/debian-installer/devel/partman/partman-doc.html/ch4.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">

<html>

<head>

<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">

<title>Partition Management for the Debian Installer - /lib/partman/lib/*</title>

<link href="index.html" rel="start">
<link href="ch3.html" rel="prev">
<link href="ch5.html" rel="next">
<link href="index.html#contents" rel="contents">
<link href="index.html#copyright" rel="copyright">
<link href="ch1.html" rel="chapter" title="1 Introduction">
<link href="ch2.html" rel="chapter" title="2 Changes in partman since 2005">
<link href="ch3.html" rel="chapter" title="3 Package interrelations">
<link href="ch4.html" rel="chapter" title="4 /lib/partman/lib/*">
<link href="ch5.html" rel="chapter" title="5 The commands of parted_server">
<link href="ch6.html" rel="chapter" title="6 Bugs and limitations">
<link href="ch3.html#s-basics" rel="section" title="3.1 Basics">
<link href="ch3.html#s-menudirs" rel="section" title="3.2 Menu-directories">
<link href="ch3.html#s3.3" rel="section" title="3.3 Partitioning">
<link href="ch3.html#s3.4" rel="section" title="3.4 Setup /target">
<link href="ch4.html#s4.1" rel="section" title="4.1 Environment">
<link href="ch4.html#s4.2" rel="section" title="4.2 Menus">
<link href="ch4.html#s4.3" rel="section" title="4.3 Long numbers">
<link href="ch4.html#s-update_partitions" rel="section" title="4.4 Updating partition directories">
<link href="ch4.html#s4.5" rel="section" title="4.5 Communication with parted_server">
<link href="ch5.html#s5.1" rel="section" title="5.1 Open a new device">
<link href="ch5.html#s5.2" rel="section" title="5.2 Close a device">
<link href="ch5.html#s5.3" rel="section" title="5.3 Does the partition exist on the disk?">
<link href="ch5.html#s5.4" rel="section" title="5.4 Remember the partition table as unchanged">
<link href="ch5.html#s5.5" rel="section" title="5.5 Report whether the partition table is changed">
<link href="ch5.html#s5.6" rel="section" title="5.6 Dump the partitions">
<link href="ch5.html#s5.7" rel="section" title="5.7 Write partitioning to the disk">
<link href="ch5.html#s5.8" rel="section" title="5.8 Undo the changes">
<link href="ch5.html#s5.9" rel="section" title="5.9 Get the partitions">
<link href="ch5.html#s5.10" rel="section" title="5.10 Getting info about a partition">
<link href="ch5.html#s5.11" rel="section" title="5.11 Getting cylinder/head/sector geometry of a partition/free space">
<link href="ch5.html#s5.12" rel="section" title="5.12 Getting the supported partition table types">
<link href="ch5.html#s5.13" rel="section" title="5.13 Get the type of the disk label">
<link href="ch5.html#s5.14" rel="section" title="5.14 Create a new empty partition table">
<link href="ch5.html#s5.15" rel="section" title="5.15 Getting the meaningful flags for a partition">
<link href="ch5.html#s5.16" rel="section" title="5.16 Getting the active flags of a partition">
<link href="ch5.html#s5.17" rel="section" title="5.17 Set the flags of a partition">
<link href="ch5.html#s5.18" rel="section" title="5.18 Check if partition names are supported">
<link href="ch5.html#s5.19" rel="section" title="5.19 Set the name of a partition">
<link href="ch5.html#s5.20" rel="section" title="5.20 Get the maximum number of primary partitions">
<link href="ch5.html#s5.21" rel="section" title="5.21 Check if extended and logical partitions are supported">
<link href="ch5.html#s5.22" rel="section" title="5.22 Get the known to parted_server file systems">
<link href="ch5.html#s5.23" rel="section" title="5.23 Try to detect the file system in a partition">
<link href="ch5.html#s5.24" rel="section" title="5.24 Change the filesystem of a partition">
<link href="ch5.html#s5.25" rel="section" title="5.25 Check the filesystem in a partition for errors">
<link href="ch5.html#s5.26" rel="section" title="5.26 Create a file system in a partition">
<link href="ch5.html#s5.27" rel="section" title="5.27 Create a new partition">
<link href="ch5.html#s5.28" rel="section" title="5.28 Delete a partition">
<link href="ch5.html#s5.29" rel="section" title="5.29 Resize a partition">
<link href="ch5.html#s5.30" rel="section" title="5.30 Get resize range">
<link href="ch5.html#s5.31" rel="section" title="5.31 Copy the contents of one partition into another">

</head>

<body>

<p><a name="ch4"></a></p>
<hr>

<p>
[ <a href="ch3.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch1.html">1</a> ]
[ <a href="ch2.html">2</a> ]
[ <a href="ch3.html">3</a> ]
[ 4 ]
[ <a href="ch5.html">5</a> ]
[ <a href="ch6.html">6</a> ]
[ <a href="ch5.html">next</a> ]
</p>

<hr>

<h1>
Partition Management for the Debian Installer
<br>Chapter 4 - <code>/lib/partman/lib/*</code>
</h1>

<hr>

<p>
Various scripts in partman make use of <em>function libraries</em>: separate
files, mostly containing shell functions, that are sourced by scripts so they
can make use of common functions and code duplication can be avoided.
</p>

<p>
The main function library is <code>base.sh</code>, provided by
<code>partman-base</code>.  This file is sourced by most scripts in partman as
it defines a lot of useful variables and common functions.  Some of these are
documented in the remainder of this chapter.  [<a href="footnotes.html#f5"
name="fr5">5</a>]
</p>

<p>
Other packages provide more targeted function libraries.  In most cases their
scope and use can easily be determined from their name.
</p>

<hr>

<h2 id="s4.1">4.1 Environment</h2>

<p>
The variables <samp>TAB</samp> and <samp>NL</samp> have values ASCII&nbsp;9 and
ASCII&nbsp;10 correspondingly.  They can be used as temporary values for the
variable <samp>IFS</samp>.  The function <code>restore_ifs</code> restores the
variable <samp>IFS</samp> its original value.
</p>

<p>
The function library <code>base.sh</code> also contains simple
reimplementations of <code>basename</code> and <code>dirname</code> so that
busybox doesn't have to provide them.
</p>

<hr>

<h2 id="s4.2">4.2 Menus</h2>

<p>
The function <code>debconf_select</code> is a high level function to ask user
with a menu using a Debconf question with type `select'.  Synopsis:
</p>

<pre>
     debconf_select <var>priority</var> <var>template</var> <var>choices</var> <var>default</var>
</pre>

<p>
The first argument is the debconf-priority of the question and the second is
the name of the template to be used.  The third argument is a newline-separated
list of items for the menu.  Each item has the form
</p>

<pre>
     <var>menu_item_id</var>&lt;TAB&gt;The text for the user
</pre>

<p>
Here <samp>&lt;TAB&gt;</samp> is ASCII&nbsp;9.  The text `The text for the
user' is the text of the menu item.  If <var><samp>menu_item_id</samp></var> of
some menu-item is identical with the fourth argument given to
<code>debconf_select</code> then this menu-item will be default.
</p>

<p>
If the user cancels the question <code>debconf_select</code> returns with
exit-code 255.  Otherwise the value of the variable <samp>RET</samp> will be
the <var><samp>menu_item_id</samp></var> of the chosen menu item.  If the
chosen menu item was chosen by the user then the exit-code is 0.  If the item
was chosen automatically (due to the debconf-priority or to some other reason)
the exit-code is 1.
</p>

<p>
The function <code>debconf_select</code> doesn't care to <code>db_fset</code>
<samp>$template</samp> <samp>seen</samp> <samp>false</samp>.  The template must
have exactly the following type and choices fields:
</p>

<pre>
     Type: select
     Choices-C: ${CHOICES}
     Choices: ${DESCRIPTIONS}
</pre>

<p>
The udebs that generate menus using menu-directories use the function
<code>ask_user</code> instead of <code>debconf_select</code>.  Synopsis:
</p>

<pre>
     ask_user <var>a_menu_directory</var> <var>aditional_optional_arguments</var>...
</pre>

<p>
This function displays the menu for <samp><var>a_menu_directory</var></samp>.
The first argument is a menu-directory (see <a
href="ch3.html#s-menudirs">Menu-directories, Section 3.2</a>).  If the user
cancels the dialog then <code>ask_user</code> returns with exit code 255.
Otherwise it returns with the exit code of the script <code>do_option</code>.
</p>

<p>
If <code>ask_user</code> is called re-entrantly from within a
<code>do_option</code> script, then the calling <code>do_option</code> script
should typically be careful to handle or discard exit code 255 itself (and
sometimes other codes, depending on the protocol in force) to avoid a backup
operation inadvertently backing up out of several nested menus at once.
</p>

<p>
The script <code>choices</code> is invoked with
<var><samp>aditional_optional_arguments</samp></var> as arguments.  The first
argument given to <code>do_option</code> is the
<var><samp>menu_item_id</samp></var> of the chosen menu item and the other
arguments are again <var><samp>aditional_optional_arguments</samp></var>.
</p>

<p>
To set the default selected item in a menu-directory, use the function
<code>menudir_default_choice</code>.  Synopsis:
</p>

<pre>
     menudir_default_choice <var>a_menu_directory</var> <var>subdirectory</var> <var>menu_item_id</var>
</pre>

<p>
Where the <var><samp>subdirectory</samp></var> is the name of a subdirectory in
the menu-directory with the leading sequence number stripped off and
<var><samp>menu_item_id</samp></var> is the id of a menu-item printed by
<code><var>a_menu_directory</var>/??<var>subdirectory</var>/choices</code>.
The specified item is set as default not forever but only for the next
invocation of <code>ask_user</code>.  It is not an error to set as default
non-existing item; in this case the first item in the menu will be default.
</p>

<p>
The function <code>partition_tree_choices</code> prints a sequence of lines in
the form
</p>

<pre>
     <var>menu_item_id</var>&lt;TAB&gt;The text for the user
</pre>

<p>
&ndash; one for every storage device and one for every partition.  The
<var><samp>menu_item_id</samp></var> of the storage devices is their storage
directory.  The <var><samp>menu_item_id</samp></var> of the partitions has the
form <var>storage_directory</var>//<var>partition_id</var>.  The output of
<code>partition_tree_choices</code> can be given as third argument to
<code>debconf_select</code>.
</p>

<hr>

<h2 id="s4.3">4.3 Long numbers</h2>

<p>
Notice that the sizes of most of the present storage devices are so large that
we cannot measure them using 32-bit integers.  Consequently we cannot use the
usual shell arithmetic.  The functions <code>longint_le</code>,
<code>longint2human</code>, <code>human2longint</code> and
<code>valid_human</code> exist in order to deal with such big numbers.
</p>

<p>
The function <code>longint_le</code> is used to compare two big numbers.
</p>

<pre>
     longint_le <var>number1</var> <var>number2</var>
</pre>

<p>
returns with exit code&nbsp;0 if the first number is less or equal to the
second and returns 1 otherwise.
</p>

<p>
The function <code>longint2human</code> accepts in its first argument some
number of bytes, converts it to something that is more meaningful for humans
and outputs the result.  For example
</p>

<pre>
     longint2human 1234567890
</pre>

<p>
gives <samp>1.2 GB</samp>.  Notice that this function rounds its argument.
</p>

<p>
The function <code>human2longint</code> is used for the opposite convertion:
</p>

<pre>
     human2longint 1.234Gb
</pre>

<p>
gives <samp>1234000000</samp>.
</p>

<p>
The function <code>valid_human</code> returns with exit code&nbsp;0 when its
first argument is a string that is suitable to be given to
<code>human2longint</code>.  Otherwise it returns with exit code&nbsp;1.
</p>

<hr>

<h2 id="s-update_partitions">4.4 Updating partition directories</h2>

<p>
Different components of the installer may need to get information about the
partitions.  They can communicate with <code>parted_server</code> in order to
know the characteristics of the partition.  However not everything can be known
from <code>parted_server</code>.  Imagine an udeb that provides the user with
the option to upgrade some existing GNU/Linux installation.  This udeb analyses
the <code>fstab</code> and knows that some partition is used as
<code>/home</code> and should not be formatted.  This sort of information has
nothing to do with <code>parted_server</code>.  The udeb stores it in a
subdirectory of the device directory named after the id of the partition.
</p>

<p>
But now a problem arises.  Suppose that the user chooses to format some
partition as ext2 and mount it on <code>/home</code>.  The udebs responsible
for formatting and mounting create the directories <code>filesystem</code> and
<code>mountpoint</code> in the partition.  What will happen if the users change
their mind and decide to use the same partition as swap space?  Swap spaces
have no mount points and the file <code>mountpoint</code> should be removed.
Who is responsible for removing it?  The udeb that allows the user to choose a
file system for the partition doesn't have to know that swap-spaces have no
mount points, only the udeb that provides support for swap-spaces can know that
the file <code>mountpoint</code> should be removed.
</p>

<p>
In order to solve this difficulty every script that makes changes to some
partition should invoke the function <code>update_partition</code> from
<code>base.sh</code>.  Synopsis:
</p>

<pre>
     update_partition <var>device_directory</var> <var>partition_id</var>
</pre>

<p>
In order to update the contents of the directory
<code><var>device_directory</var>/<var>partition_id</var></code> the function
<code>update_partition</code> executes the scripts from the directory
<code>/lib/partman/update.d/</code>.  Every udeb is allowed to install scripts
in this directory.  Their names are prefixed by two-digit numbers that control
the order of the execution.  The scripts from <code>update.d</code> are given
several arguments.  $1 is the <var>device_directory</var>.  $2 is the number of
the partition (<code>/dev/hda6</code> will have number 6).  $3 is the id of the
partition.  $4 is the length of the partition (in bytes).  $5 is the type of
the partition, it can be either `primary' or `logical'.  $6 is the type of the
file system as known to <code>parted_server</code>, in most cases you should
ignore this argument.  $7 is the device name (for example
<code>/dev/ide/host0/bus0/target0/lun0/part6</code>).
&quot;$8&nbsp;$9&nbsp;$10&nbsp;$11&nbsp;...&quot; is the name of the partition
in partition tables that support partition names.  Otherwise $8, $9, $10,...
are not defined.
</p>

<hr>

<h2 id="s4.5">4.5 Communication with <code>parted_server</code></h2>

<p>
The package <code>partman-base</code> creates two FIFOs &ndash;
<code>/var/lib/partman/infifo</code> and <code>/var/lib/partman/outfifo</code>.
<code>Parted_server</code> reads instructions from <code>infifo</code> and
responds by writting to <code>outfifo</code>.  Consequently the clients write
to <code>infifo</code> and read from <code>outfifo</code>.  The function
library <code>base.sh</code> contain several functions to make the
communication with <code>parted_server</code> easier.  Here we will omit the
details, if you want to know the exact communication protocol please read how
these functions are implemented.
</p>

<p>
The functions <code>open_infifo</code>, <code>close_infifo</code>,
<code>open_outfifo</code> and <code>close_outfifo</code> are called without
arguments.  They open and close <code>infifo</code> and <code>outfifo</code>
assigning them file descriptors 6 and 7 correspondingly.  You do not need to
use these low-level functions.
</p>

<p>
The function <code>write_line</code> prints its arguments to
<code>outfifo</code>.
</p>

<p>
The function <code>read_line</code> reads from <code>infifo</code> a line,
splits it in fields according to <samp>$IFS</samp> and assigns these fields to
variables whose names are given to <code>read_line</code> as arguments.  For
example
</p>

<pre>
     read_line x y z
</pre>

<p>
reads a line from <code>infifo</code>, splits it and assigns the first field to
the variable <samp>x</samp>, the second field to the variable <samp>y</samp>
and the rest to the variable <samp>z</samp>.  You see that
<code>read_line</code> is used the same way as the shell operator
<code>read</code>.
</p>

<p>
The function <code>read_paragraph</code> reads consequently lines from
<code>infifo</code> until it reaches an empty line.  It prints the read lines
with the exception of the last empty line.
</p>

<p>
The function <code>read_list</code> reads lines the same way as the function
<code>read_paragraph</code>.  However the function <code>read_list</code>
always prints only one line that is a comma-separated sequence of the lines
read from <code>infifo</code>.  If <code>read_paragraph</code> prints
</p>

<pre>
     This is the first line
     This is the second line
     This is the third line
</pre>

<p>
<code>read_list</code> prints
</p>

<pre>
     This is the first line, This is the second line, This is the third line
</pre>

<p>
In order to initiate a communication dialog with <code>parted_server</code> you
will use the function <code>open_dialog</code>.  You will invoke it in the
device directory of the device you want to issue command about.  The first
argument of <code>open_dialog</code> is a command for
<code>parted_server</code>.  The rest arguments are arguments for the command.
</p>

<p>
You use the function <code>close_dialog</code> in order to terminate the
communication dialog.
</p>

<p>
When you send <code>parted_server</code> an order to do some long operation
(check, create, resize or copy file system) the user will be shown a progress
bar.  You may give name to it by the function <code>name_progress_bar</code>.
It may be used right before the command <code>open_dialog</code> and accepts
only one argument &ndash; a template with type text that describes what is
being done.
</p>

<p>
The function <code>log</code> appends its arguments to the file
<code>/var/log/partman</code>.  This file is used as log-file also by
<code>parted_server</code>.
</p>

<hr>

<p>
[ <a href="ch3.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch1.html">1</a> ]
[ <a href="ch2.html">2</a> ]
[ <a href="ch3.html">3</a> ]
[ 4 ]
[ <a href="ch5.html">5</a> ]
[ <a href="ch6.html">6</a> ]
[ <a href="ch5.html">next</a> ]
</p>

<hr>

<p>
Partition Management for the Debian Installer
</p>

<address>
Anton Zinoviev <code><a href="mailto:anton@lml.bas.bg">mailto:anton@lml.bas.bg</a></code><br>
<br>
</address>
<hr>

</body>

</html>
debian-installer 20101020ubuntu543 / usr / share / doc / debian-installer / devel / partman / partman-doc.html / ch4.html
