Documentation
¶
Overview ¶
Package cpio implements utilities for reading and writing cpio archives.
Currently, only newc-formatted cpio archives are supported through cpio.Newc.
Reading from or writing to a file:
f, err := os.Open(...)
if err ...
recReader := cpio.Newc.Reader(f)
err := ForEachRecord(recReader, func(r cpio.Record) error {
})
// Or...
recWriter := cpio.Newc.Writer(f)
Reading from or writing to an in-memory archive:
a := cpio.InMemArchive()
err := a.WriteRecord(...)
recReader := a.Reader() // Reads from the "beginning."
if a.Contains("bar/foo") {
}
Index ¶
- Constants
- Variables
- func AllEqual(r []Record, s []Record) bool
- func Concat(w RecordWriter, r RecordReader, transform func(Record) Record) error
- func CreateFile(f Record) error
- func CreateFileInRoot(f Record, rootDir string, forcePriv bool) error
- func Equal(r Record, s Record) bool
- func ForEachRecord(rr RecordReader, fun func(Record) error) error
- func LSInfoFromRecord(rec Record) ls.FileInfo
- func MakeAllReproducible(files []Record)
- func Normalize(path string) string
- func Passthrough(r RecordReader, w RecordWriter) error
- func WriteRecords(w RecordWriter, files []Record) error
- func WriteTrailer(w RecordWriter) error
- type Archive
- type DedupWriter
- type EOFReader
- type Info
- type Record
- func CharDev(name string, perm uint64, rmajor, rminor uint64) Record
- func Directory(name string, mode uint64) Record
- func MakeReproducible(r Record) Record
- func ReadAllRecords(rr RecordReader) ([]Record, error)
- func StaticFile(name string, content string, perm uint64) Record
- func StaticRecord(contents []byte, info Info) Record
- func Symlink(name string, target string) Record
- type RecordFormat
- type RecordReader
- type RecordWriter
- type Recorder
Constants ¶
const ( S_IEXEC = 0x40 S_IFBLK = 0x6000 S_IFCHR = 0x2000 S_IFDIR = 0x4000 S_IFIFO = 0x1000 S_IFLNK = 0xa000 S_IFMT = 0xf000 S_IFREG = 0x8000 S_IFSOCK = 0xc000 S_IFWHT = 0xe000 S_IREAD = 0x100 S_IRGRP = 0x20 S_IROTH = 0x4 S_IRUSR = 0x100 S_IRWXG = 0x38 S_IRWXO = 0x7 S_IRWXU = 0x1c0 S_ISGID = 0x400 S_ISTXT = 0x200 S_ISUID = 0x800 S_ISVTX = 0x200 )
These Unix constants are needed everywhere cpio is used, Unix or not. But we are unable to import the unix package when plan 9 is enabled, so lucky us, the numbers have been the same for half a century. It is ok to just define them.
const Trailer = "TRAILER!!!"
Trailer is the name of the trailer record.
Variables ¶
var ( // Debug can be set e.g. to log.Printf to enable debug prints from // marshaling/unmarshaling cpio archives. Debug = func(string, ...interface{}) {} )
var TrailerRecord = StaticRecord(nil, Info{Name: Trailer})
TrailerRecord is the last record in any CPIO archive.
Functions ¶
func Concat ¶
func Concat(w RecordWriter, r RecordReader, transform func(Record) Record) error
Concat reads files from r one at a time, and writes them to w.
Concat does not write a trailer record and applies transform to every record before writing it. transform may be nil.
func CreateFile ¶
CreateFile creates a local file for f relative to the current working directory.
CreateFile will attempt to set all metadata for the file, including ownership, times, and permissions.
func CreateFileInRoot ¶
CreateFileInRoot creates a local file for f relative to rootDir.
It will attempt to set all metadata for the file, including ownership, times, and permissions. If these fail, it only returns an error if forcePriv is true.
Block and char device creation will only return error if forcePriv is true.
func ForEachRecord ¶
func ForEachRecord(rr RecordReader, fun func(Record) error) error
ForEachRecord reads every record from r and applies f.
func LSInfoFromRecord ¶
LSInfoFromRecord converts a Record to be usable with the ls package for listing files.
func MakeAllReproducible ¶
func MakeAllReproducible(files []Record)
MakeAllReproducible makes all given records reproducible as in MakeReproducible.
func Passthrough ¶
func Passthrough(r RecordReader, w RecordWriter) error
Passthrough copies from a RecordReader to a RecordWriter.
Passthrough writes a trailer record.
It processes one record at a time to minimize the memory footprint.
func WriteRecords ¶
func WriteRecords(w RecordWriter, files []Record) error
WriteRecords writes multiple records to w.
Types ¶
type Archive ¶
type Archive struct {
// Files is a map of relative archive path -> record.
Files map[string]Record
// Order is a list of relative archive paths and represents the order
// in which Files were added.
Order []string
}
Archive is an in-memory list of files.
Archive itself is a RecordWriter, and Archive.Reader() returns a new RecordReader for the archive starting from the first file.
func ArchiveFromReader ¶
func ArchiveFromReader(r RecordReader) (*Archive, error)
ArchiveFromReader reads records from r into a new Archive in memory.
func ArchiveFromRecords ¶
ArchiveFromRecords creates a new Archive from the records.
func (*Archive) Get ¶
Get returns a record for the normalized path or false if there is none.
The path is normalized using Normalize, so Get("/bin/bar") is the same as Get("bin/bar") is the same as Get("bin//bar").
func (*Archive) Reader ¶
func (a *Archive) Reader() RecordReader
Reader returns a RecordReader for the archive that starts at the first record.
func (*Archive) WriteRecord ¶
WriteRecord implements RecordWriter and adds a record to the archive.
WriteRecord uses Normalize to deduplicate paths.
type DedupWriter ¶
type DedupWriter struct {
// contains filtered or unexported fields
}
DedupWriter is a RecordWriter that does not write more than one record with the same path.
There seems to be no harm done in stripping duplicate names when the record is written, and lots of harm done if we don't do it.
func (*DedupWriter) WriteRecord ¶
func (dw *DedupWriter) WriteRecord(rec Record) error
WriteRecord implements RecordWriter.
If rec.Name was already seen once before, it will not be written again and WriteRecord returns nil.
type EOFReader ¶
type EOFReader struct {
RecordReader
}
EOFReader is a RecordReader that converts the Trailer record to io.EOF.
func (EOFReader) ReadRecord ¶
ReadRecord implements RecordReader.
ReadRecord returns io.EOF when the record name is TRAILER!!!.
type Info ¶
type Info struct {
Ino uint64
Mode uint64
UID uint64
GID uint64
NLink uint64
MTime uint64
FileSize uint64
Dev uint64
Major uint64
Minor uint64
Rmajor uint64
Rminor uint64
Name string
}
Info holds metadata about files.
type Record ¶
type Record struct {
// ReaderAt contains the content of this CPIO record.
io.ReaderAt
// Info is metadata describing the CPIO record.
Info
// metadata about this item's place in the file
RecPos int64 // Where in the file this record is
RecLen uint64 // How big the record is.
FilePos int64 // Where in the CPIO the file's contents are.
}
Record represents a CPIO record, which represents a Unix file.
func MakeReproducible ¶
MakeReproducible changes any fields in a Record such that if we run cpio again, with the same files presented to it in the same order, and those files have unchanged contents, the cpio file it produces will be bit-for-bit identical. This is an essential property for firmware-embedded payloads.
func ReadAllRecords ¶
func ReadAllRecords(rr RecordReader) ([]Record, error)
ReadAllRecords returns all records in r in the order in which they were read.
func StaticFile ¶
StaticFile returns a normal file record.
func StaticRecord ¶
StaticRecord returns a record with the given contents and metadata.
type RecordFormat ¶
type RecordFormat interface {
Reader(r io.ReaderAt) RecordReader
Writer(w io.Writer) RecordWriter
}
A RecordFormat gives readers and writers for dealing with archives from io objects.
CPIO files have a number of records, of which newc is the most widely used today.
var ( // Newc is the newc CPIO record format. Newc RecordFormat = newc{/* contains filtered or unexported fields */} )
func Format ¶
func Format(name string) (RecordFormat, error)
Format returns the RecordFormat with that name, if it exists.
type RecordReader ¶
A RecordReader reads one record from an archive.
type RecordWriter ¶
A RecordWriter writes one record to an archive.
func NewDedupWriter ¶
func NewDedupWriter(rw RecordWriter) RecordWriter
NewDedupWriter returns a new deduplicating rw.
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
A Recorder is a structure that contains variables used to calculate file parameters such as inode numbers for a CPIO file. The life-time of a Record structure is meant to be the same as the construction of a single CPIO archive. Do not reuse between CPIOs if you don't know what you're doing.
func NewRecorder ¶
func NewRecorder() *Recorder
NewRecorder creates a new Recorder.
A recorder is a structure that contains variables used to calculate file parameters such as inode numbers for a CPIO file. The life-time of a Record structure is meant to be the same as the construction of a single CPIO archive. Do not reuse between CPIOs if you don't know what you're doing.
Source Files