mmap

README

mmap

Package mmap provides ways to mmap a file.

This started as a fork of golang.org/x/exp/mmap.

Installation

$> go get codeberg.org/go-mmap/mmap

Documentation

Overview

Package mmap provides a way to memory-map a file.

Index

• type File
  • func Open(filename string) (*File, error)
  • func OpenFile(filename string, flag Flag) (*File, error)
  • func (f *File) At(i int) byte
  • func (f *File) Close() error
  • func (f *File) Len() int
  • func (f *File) Read(p []byte) (int, error)
  • func (f *File) ReadAt(p []byte, off int64) (int, error)
  • func (f *File) ReadByte() (byte, error)
  • func (f *File) Seek(offset int64, whence int) (int64, error)
  • func (f *File) Stat() (os.FileInfo, error)
  • func (f *File) Sync() error
  • func (f *File) Write(p []byte) (int, error)
  • func (f *File) WriteAt(p []byte, off int64) (int, error)
  • func (f *File) WriteByte(c byte) error
• type Flag

Examples

• Open
• OpenFile (Read)
• OpenFile (Readwrite)

Types

type File

type File struct {
	// contains filtered or unexported fields
}

File reads/writes a memory-mapped file.

func Open

func Open(filename string) (*File, error)

Open memory-maps the named file for reading.

Example

package main

import (
	"fmt"
	"log"

	"codeberg.org/go-mmap/mmap"
)

func main() {
	f, err := mmap.Open("example_mmap_test.go")
	if err != nil {
		log.Fatalf("could not mmap file: %+v", err)
	}
	defer f.Close()

	buf := make([]byte, 32)
	_, err = f.Read(buf)
	if err != nil {
		log.Fatalf("could not read into buffer: %+v", err)
	}

	fmt.Printf("%s\n", buf[:12])

}

Output:
// Copyright

func OpenFile

func OpenFile(filename string, flag Flag) (*File, error)

OpenFile memory-maps the named file for reading/writing, depending on the flag value.

Example (Read)

package main

import (
	"fmt"
	"log"

	"codeberg.org/go-mmap/mmap"
)

func main() {
	f, err := mmap.OpenFile("example_mmap_test.go", mmap.Read)
	if err != nil {
		log.Fatalf("could not mmap file: %+v", err)
	}
	defer f.Close()

	buf := make([]byte, 32)
	_, err = f.ReadAt(buf, 0)
	if err != nil {
		log.Fatalf("could not read into buffer: %+v", err)
	}

	fmt.Printf("%s\n", buf[:12])

}

Output:
// Copyright

Example (Readwrite)

package main

import (
	"fmt"
	"log"
	"os"

	"codeberg.org/go-mmap/mmap"
)

func main() {
	f, err := os.CreateTemp("", "mmap-")
	if err != nil {
		log.Fatalf("could not create tmp file: %+v", err)
	}
	defer f.Close()
	defer os.Remove(f.Name())

	_, err = f.Write([]byte("hello world!"))
	if err != nil {
		log.Fatalf("could not write data: %+v", err)
	}

	err = f.Close()
	if err != nil {
		log.Fatalf("could not close file: %+v", err)
	}

	raw, err := os.ReadFile(f.Name())
	if err != nil {
		log.Fatalf("could not read back data: %+v", err)
	}

	fmt.Printf("%s\n", raw)

	rw, err := mmap.OpenFile(f.Name(), mmap.Read|mmap.Write)
	if err != nil {
		log.Fatalf("could not open mmap file: %+v", err)
	}
	defer rw.Close()

	_, err = rw.Write([]byte("bye!"))
	if err != nil {
		log.Fatalf("could not write to mmap file: %+v", err)
	}

	raw, err = os.ReadFile(f.Name())
	if err != nil {
		log.Fatalf("could not read back data: %+v", err)
	}

	fmt.Printf("%s\n", raw)

}

Output:
hello world!
bye!o world!

func (*File) At

func (f *File) At(i int) byte

At returns the byte at index i.

func (*File) Close

func (f *File) Close() error

Close closes the memory-mapped file.

func (*File) Len

func (f *File) Len() int

Len returns the length of the underlying memory-mapped file.

func (*File) Read

func (f *File) Read(p []byte) (int, error)

Read implements the io.Reader interface.

func (*File) ReadAt

func (f *File) ReadAt(p []byte, off int64) (int, error)

ReadAt implements the io.ReaderAt interface.

func (*File) ReadByte

func (f *File) ReadByte() (byte, error)

ReadByte implements the io.ByteReader interface.

func (*File) Seek

func (f *File) Seek(offset int64, whence int) (int64, error)

func (*File) Stat

func (f *File) Stat() (os.FileInfo, error)

Stat returns the FileInfo structure describing file. If there is an error, it will be of type *os.PathError.

func (*File) Sync

func (f *File) Sync() error

Sync commits the current contents of the file to stable storage.

func (*File) Write

func (f *File) Write(p []byte) (int, error)

Write implements the io.Writer interface.

func (*File) WriteAt

func (f *File) WriteAt(p []byte, off int64) (int, error)

WriteAt implements the io.WriterAt interface.

func (*File) WriteByte

func (f *File) WriteByte(c byte) error

WriteByte implements the io.ByteWriter interface.

type Flag

type Flag int

Flag specifies how a mmap file should be opened.

const (
	Read  Flag = 0x1 // Read enables read-access to a mmap file.
	Write Flag = 0x2 // Write enables write-access to a mmap file.
)