memfd

README

Go Memfd library

This is a Go library for working with Linux memfd, memory file descriptors.

These provide shareable anonymous memory, which can be passed around via file descriptors, and also locked from write or resize. They are designed to let programs that do not trust each other communicate via shared memory without issues of naming, truncation, or race conditions due to modifications.

For more information about the underlying syscalls see memfd_create and the file sealing section of fcntl. There is also a sealed files overview from LWN, but written slightly before the final design was merged, so the details are not quite correct for the final version.

The functionality was added in Linux 3.17, in February 2015. It was also added to the Debian Jessie 3.16 kernels, and is in the Ubuntu 14.04 updates, as well as being backported to the Centos 7.3/RHEL 7.3 series, so it is available in all non ancient Linux distros, so should be generally usable.. Currently there is no support in the BSDs or other non Linux systems, I hope this can be added as it is a useful interface.

A Capnproto Arena library is also included, for sending structured data between processes.

Documentation

Overview

Package memfd provides a Go library for working with Linux memfd memory file descriptors. This provides shareable anonymous memory which can be locked.

Example

mfd, err := memfd.Create()
if err != nil {
	panic(err)
}
defer mfd.Close()
_, _ = mfd.WriteString("add some contents")
err = mfd.SetImmutable()
if err != nil {
	panic(err)
}
b, err := mfd.Map()
if err != nil {
	panic(err)
}
defer mfd.Unmap()
fmt.Println(string(b))

Output:

add some contents

Index

• Constants
• Variables
• type Memfd
  • func Create() (*Memfd, error)
  • func CreateNameFlags(name string, flags uint) (*Memfd, error)
  • func New(fd uintptr) (*Memfd, error)
  • func (mfd *Memfd) ClearCloexec()
  • func (mfd *Memfd) IsImmutable() bool
  • func (mfd *Memfd) Map() ([]byte, error)
  • func (mfd *Memfd) Remap() ([]byte, error)
  • func (mfd *Memfd) Seals() int
  • func (mfd *Memfd) SetCloexec()
  • func (mfd *Memfd) SetImmutable() error
  • func (mfd *Memfd) SetSeals(seals int) error
  • func (mfd *Memfd) SetSize(size int64) error
  • func (mfd *Memfd) Size() int64
  • func (mfd *Memfd) Unmap() error

Examples

• Package

Constants

const (
	// Cloexec sets the cloexec flag on the memfd when opened
	Cloexec = msyscall.MFD_CLOEXEC
	// AllowSealing allows seal operations to be performed
	AllowSealing = msyscall.MFD_ALLOW_SEALING

	// SealSeal means no more seal operations can be performed
	SealSeal = msyscall.F_SEAL_SEAL
	// SealShrink means the memfd may no longer shrink
	SealShrink = msyscall.F_SEAL_SHRINK
	// SealGrow means the memfd may no longer grow
	SealGrow = msyscall.F_SEAL_GROW
	// SealWrite means the memfd may no longer be written to
	SealWrite = msyscall.F_SEAL_WRITE
	// SealAll means the memfd is now immutable
	SealAll = SealSeal | SealShrink | SealGrow | SealWrite
)

Variables

var (
	// ErrTooBig is returned if you try to map a memfd over 2GB on a 32 bit platform
	ErrTooBig = errors.New("memfd too large for slice")
)

Types

type Memfd

type Memfd struct {
	*os.File
	// contains filtered or unexported fields
}

Memfd is the type for an memory fd, an os.File with extra methods

func Create

func Create() (*Memfd, error)

Create creates a memfd and sets the flags to the most common options, Cloexec and AllowSealing.

func CreateNameFlags

func CreateNameFlags(name string, flags uint) (*Memfd, error)

CreateNameFlags creates a memfd, and allows setting name and flags if required. Name is not required; it is recorded as the symlink name in /proc/self/fd.

func New

func New(fd uintptr) (*Memfd, error)

New creates a memfd object from a file descriptor, eg passed via a pipe or to an exec. Will return an error if the file was not a memfd, ie cannot have seals.

func (*Memfd) ClearCloexec

func (mfd *Memfd) ClearCloexec()

ClearCloexec clears the (default) Cloexec flag. Useful just before you exec another process if you are not using the Go fork exec which can set this. While this can fail in theory, it only will if the file is closed, so we ignore error.

func (*Memfd) IsImmutable

func (mfd *Memfd) IsImmutable() bool

IsImmutable returns true if the memfd is fully immutable, all seals set

func (*Memfd) Map

func (mfd *Memfd) Map() ([]byte, error)

Map returns a byte slice with the memfd contents in. This is a private read only mapping if the memfd has a write seal, and a shared writeable mapping if it is not sealed. The slice must be under 2GB on a 32 bit platform. Writeable mappings must be unmapped before sealing. Multiple requests return the same slice.

func (*Memfd) Remap

func (mfd *Memfd) Remap() ([]byte, error)

Remap adjusts the mapping to the current size of the memfd. It may be a new slice. Implementation is currently inefficient, will rework to use mremap syscall if this is useful.

func (*Memfd) Seals

func (mfd *Memfd) Seals() int

Seals returns the current seals. It can only error if something out of the ordinary has happened, eg the file is closed, so we just return 0 (no seals) in this case.

func (*Memfd) SetCloexec

func (mfd *Memfd) SetCloexec()

SetCloexec sets the Cloexec flag. Useful if you inherited an fd with this clear. While this can fail in theory, it only will if the file is closed, so we ignore error.

func (*Memfd) SetImmutable

func (mfd *Memfd) SetImmutable() error

SetImmutable fully seals the memfd if it is not already.

func (*Memfd) SetSeals

func (mfd *Memfd) SetSeals(seals int) error

SetSeals sets the current seals. It can error if the item is sealed.

func (*Memfd) SetSize

func (mfd *Memfd) SetSize(size int64) error

SetSize sets the size of the memfd. It is just Truncate but a more understandable name.

func (*Memfd) Size

func (mfd *Memfd) Size() int64

Size returns the current size of the memfd. It could return an error if the memfd is closed; we return zero in that case.

func (*Memfd) Unmap

func (mfd *Memfd) Unmap() error

Unmap clears a mapping. Note that Close does not Unmap, it is fine to use the mapping after close, so you should usually defer Close and defer Unmap to avoid leaking resources.