/ 
Sys-Export-0.003
/ Sys::Export::CPIO

NAME

Sys::Export::CPIO - Write CPIO archives needed for Linux initrd

SYNOPSIS

my $cpio= Sys::Export::CPIO->new($file_name_or_handle, %attrs);
$cpio->add(\%stat_name_and_data);
$cpio->add(\%stat_name_and_data);
$cpio->add(\%stat_name_and_data);
...
$cpio->finish;  # write trailer entry and flush/close file.
                # file is *not* closed automatically if you passed
                # an open handle to the constructor.

DESCRIPTION

This module writes out the cpio "New ASCII Format", as required by Linux initrd. It does very little aside from packing the data, but has support for:

If you add a file with nlink > 1, it will note the dev/ino and write the data. If you record a second file also having nlink > 1 with the same dev/ino, the size will be written as zero and the data will be skipped. (this is the way cpio stores hardlinks)

rdev

You can pass the rdev received from stat, and this module makes a best-effort to break that down into the major/minor numbers needed for cpio, but perl doesn't have access to the real major/minor functions of your platform unless you install Unix::Mknod. If you were trying to creaate a device node from pure configuration rather than the filesystem, just pass rdev_major and rdev_minor instead of rdev.

virtual_inodes

Since the original device and inode are not relevant to the initrd loading, this module can replace the device with 0 and the inode with an incrementing sequence, which should compress better.

Pass (virtual_inodes => 0) to the constructor to disable this feature.

CONSTRUCTORS

new

my $cpio= Sys::Export::CPIO->new($fh_or_filename, %attrs);

The first argument is either a file handle object implementing 'print', or a file name. If it is a file name, it is immediately opened in 'raw' mode and dies on failure.

The rest of the arguments can be used to initialize attributes.

ATTRIBUTES

autoclose

If true, calling "finish" will close the file handle. This is enabled by default if you passed a filename to the constructor.

filename

Just informational for debugging. Will be undef if you passed a file handle rather than a file name to the constructor.

virtual_inodes

This is enabled by default, and rewrites the device_major/device_minor with zeroes and generates a linear sequence for a virtual inode on each file.

METHODS

add

$cpio->add({
  dev   => # or, ( dev_major =>, dev_minor => )
  ino   => # 
  mode  => #
  nlink => # same as stat() 
  uid   => # 
  gid   => # 
  mtime => #
  rdev  => # or, ( rdev_major =>, rdev_minor => )
  name  => # full path name, no leading '/'
  data  => # full content of file or symlink
});

This simply packs the file metadata into a CPIO header, then writes the header, filename, and data to the stream, padding as necessary.

finish

Writes end-of-file signature, and closes the handle if "autoclose" is true.

VERSION

version 0.003

AUTHOR

Michael Conrad <mike@nrdvana.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Michael Conrad.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.