13 Filesystem syntax and semantics
**********************************

GRUB uses a special syntax for specifying disk drives which can be
accessed by BIOS. Because of BIOS limitations, GRUB cannot distinguish
between IDE, ESDI, SCSI, or others.  You must know yourself which BIOS
device is equivalent to which OS device.  Normally, that will be clear
if you see the files in a device or use the command 'search' (*note
search::).

13.1 How to specify devices
===========================

The device syntax is like this:

     (DEVICE[,PARTMAP-NAME1PART-NUM1[,PARTMAP-NAME2PART-NUM2[,...]]])

   '[]' means the parameter is optional.  DEVICE depends on the disk
driver in use.  BIOS and EFI disks use either 'fd' or 'hd' followed by a
digit, like 'fd0', or 'cd'.  AHCI, PATA (ata), crypto, USB use the name
of driver followed by a number.  Memdisk and host are limited to one
disk and so it's refered just by driver name.  RAID (md), ofdisk
(ieee1275 and nand), LVM (lvm), LDM, virtio (vdsk) and arcdisk (arc) use
intrinsic name of disk prefixed by driver name.  Additionally just
"nand" refers to the disk aliased as "nand".  Conflicts are solved by
suffixing a number if necessarry.  Commas need to be escaped.  Loopback
uses whatever name specified to 'loopback' command.  Hostdisk uses names
specified in device.map as long as it's of the form [fhc]d[0-9]* or
hostdisk/<OS DEVICE>.  For crypto and RAID (md) additionally you can use
the syntax <driver name>uuid/<uuid>.  For LVM additionally you can use
the syntax lvmid/<volume-group-uuid>/<volume-uuid>.

     (fd0)
     (hd0)
     (cd)
     (ahci0)
     (ata0)
     (crypto0)
     (usb0)
     (cryptouuid/123456789abcdef0123456789abcdef0)
     (mduuid/123456789abcdef0123456789abcdef0)
     (lvm/system-root)
     (lvmid/F1ikgD-2RES-306G-il9M-7iwa-4NKW-EbV1NV/eLGuCQ-L4Ka-XUgR-sjtJ-ffch-bajr-fCNfz5)
     (md/myraid)
     (md/0)
     (ieee1275/disk2)
     (ieee1275//pci@1f\,0/ide@d/disk@2)
     (nand)
     (memdisk)
     (host)
     (myloop)
     (hostdisk//dev/sda)

   PART-NUM represents the partition number of DEVICE, starting from
one.  PARTNAME is optional but is recommended since disk may have
several top-level partmaps.  Specifying third and later component you
can access to subpartitions.

   The syntax '(hd0)' represents using the entire disk (or the MBR when
installing GRUB), while the syntax '(hd0,1)' represents using the first
partition of the disk (or the boot sector of the partition when
installing GRUB).

     (hd0,msdos1)
     (hd0,msdos1,msdos5)
     (hd0,msdos1,bsd3)
     (hd0,netbsd1)
     (hd0,gpt1)
     (hd0,1,3)

   If you enabled the network support, the special drives
'(PROTOCOL[,SERVER])' are also available.  Supported protocols are
'http' and 'tftp'.  If SERVER is omitted, value of environment variable
'net_default_server' is used.  Before using the network drive, you must
initialize the network.  *Note Network::, for more information.

   If you boot GRUB from a CD-ROM, '(cd)' is available.  *Note Making a
GRUB bootable CD-ROM::, for details.

13.2 How to specify files
=========================

There are two ways to specify files, by "absolute file name" and by
"block list".

   An absolute file name resembles a Unix absolute file name, using '/'
for the directory separator (not '\' as in DOS). One example is
'(hd0,1)/boot/grub/grub.cfg'.  This means the file '/boot/grub/grub.cfg'
in the first partition of the first hard disk.  If you omit the device
name in an absolute file name, GRUB uses GRUB's "root device"
implicitly.  So if you set the root device to, say, '(hd1,1)' by the
command 'set root=(hd1,1)' (*note set::), then '/boot/kernel' is the
same as '(hd1,1)/boot/kernel'.

   On ZFS filesystem the first path component must be
VOLUME'@'[SNAPSHOT].  So '/rootvol@snap-129/boot/grub/grub.cfg' refers
to file '/boot/grub/grub.cfg' in snapshot of volume 'rootvol' with name
'snap-129'.  Trailing '@' after volume name is mandatory even if
snapshot name is omitted.

13.3 How to specify block lists
===============================

A block list is used for specifying a file that doesn't appear in the
filesystem, like a chainloader.  The syntax is
'[OFFSET]+LENGTH[,[OFFSET]+LENGTH]...'.  Here is an example:

     0+100,200+1,300+300

   This represents that GRUB should read blocks 0 through 99, block 200,
and blocks 300 through 599.  If you omit an offset, then GRUB assumes
the offset is zero.

   Like the file name syntax (*note File name syntax::), if a blocklist
does not contain a device name, then GRUB uses GRUB's "root device".  So
'(hd0,2)+1' is the same as '+1' when the root device is '(hd0,2)'.