posix

package module
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 7, 2022 License: MIT Imports: 5 Imported by: 2

README

Posix

This package contains the necessary functions for POSIX shared memory management, Linux and MacOSx The POSIX shared memory API allows processes to communicate information by sharing a region of memory.

Golang doesn't have shm_open implementation and Mmap is not exposing the address parameter, needed for cross programming maps.

I highly recommend to use golang.org/x/sys (which this code is base from) if you don't require mmap with fixed memory address or shm_open function.

According to the Linux manual this package contains the following functions.

  • ShmOpen Create and open a new object, or open an existing object. The call returns a file descriptor for use by the other interfaces listed below.

  • Ftruncate Set the size of the shared memory object. (A newly created shared memory object has a length of zero.)

  • Mmap Map the shared memory object into the virtual address space of the calling process.

  • Munmap Unmap the shared memory object from the virtual address space of the calling process.

  • ShmUnlink Remove a shared memory object name.

  • Close Close the file descriptor allocated by shm_open(3) when it is no longer needed.

  • Fstat Obtain a stat structure that describes the shared memory object. Among the information returned by this call are the object's size (st_size), permissions (st_mode), owner (st_uid), and group (st_gid).

  • Fchown To change the ownership of a shared memory object.

  • Fchmod To change the permissions of a shared memory object.

  • MemfdCreate This function is available since Linux 3.17, basically creates an anonymous memory file descriptor.

Example

host

package main

import (
  "fmt"
  "gopkg.in/ro-ag/posix.v1"
  "log"
  "syscall"
  "unsafe"
)

const AppAddress uintptr = 0x20000000000 // Approximated Address 

type Head struct {
  Addr     unsafe.Pointer
  MemSize  uintptr
  TextSize uintptr
  TextPtr  unsafe.Pointer
}

type Holder struct {
  *Head
  Data []byte
}

func main() {
  // Create File Descriptor	
  fd, err := posix.MemfdCreate("From-Main", posix.MFD_ALLOW_SEALING)
  CheckErr(err)
  // Truncate File max len
  MemSize := posix.Getpagesize() * 4
  err = posix.Ftruncate(fd, MemSize)
  CheckErr(err)

  // mmap returns the map address from system call, 
  // because is not MAP_FIXED will return the closest memory if the address segment is used

  buf, addr, err := posix.Mmap(unsafe.Pointer(AppAddress), MemSize, posix.PROT_WRITE, posix.MAP_SHARED, fd, 0)
  CheckErr(err)

  text := "This works as Mmap in C"
  offset := unsafe.Sizeof(Head{})

  // Unsafe Structure, Easy for writing pointers
  hdr := (*Head)(unsafe.Pointer(&buf[0]))
  hdr.Addr = unsafe.Pointer(addr)
  hdr.MemSize = uintptr(MemSize)
  hdr.TextSize = uintptr(len(text))
  hdr.TextPtr = unsafe.Pointer(&buf[offset])

  holder := &Holder{
    Head: hdr,
    Data: unsafe.Slice(&buf[offset], uintptr(len(text))),
  }

  fmt.Println(holder)

  // Detailed code under ./example folder 

  CheckErr(posix.Munmap(buf)) // unmap memory
  CheckErr(posix.Close(fd))   // close anonymous file

}

// CheckErr wraps around error
func CheckErr(err error) {
  if err != nil {
    no := err.(syscall.Errno)
    log.Fatalf("%s(%d): %v, msg: %s\nhelp: %s", posix.ErrnoName(no), no, err, posix.ErrnoString(no), posix.ErrnoHelp(no))
  }
}

Documentation

Overview

Package posix is a golang implementation for mmap, shm_open for MacOSx and Linux without CGO ! MacOSx has an emulation for memfd_create using shm_open.

Index

Constants

View Source 
const (
	EINVAL     = syscall.EINVAL
	EAGAIN     = syscall.EAGAIN
	ENOENT     = syscall.ENOENT
	EFAULT     = syscall.EFAULT
	O_RDWR     = syscall.O_RDWR     // open for reading and writing
	O_CREAT    = syscall.O_CREAT    // create if nonexistent
	O_EXCL     = syscall.O_EXCL     // error if already exists
	O_NOFOLLOW = syscall.O_NOFOLLOW // don't follow symlinks
	O_RDONLY   = syscall.O_RDONLY   // open for reading only
	O_WRONLY   = syscall.O_WRONLY   // open for writing only
	O_ACCMODE  = syscall.O_ACCMODE  // mask for modes O_RDONLY & O_WRONLY
	O_CLOEXEC  = syscall.O_CLOEXEC
)
View Source 
const (
	PROT_NONE  = syscall.PROT_NONE  // The memory cannot be accessed at all.
	PROT_READ  = syscall.PROT_READ  // The memory can be read.
	PROT_WRITE = syscall.PROT_WRITE // The memory can be modified.
	PROT_EXEC  = syscall.PROT_EXEC  // The memory can be executed.
	PROT_RDWR  = PROT_READ | PROT_WRITE
)
View Source 
const (
	S_IRUSR    = syscall.S_IRUSR  // Read permission bit for the owner of the file. On many systems this bit is 0400.
	S_IREAD    = syscall.S_IREAD  // Deprecated: S_IREAD is an Obsolete synonym provided for BSD compatibility
	S_IWUSR    = syscall.S_IWUSR  // Write permission bit for the owner of the file. Usually 0200.
	S_IWRITE   = syscall.S_IWRITE // Deprecated: S_IWRITE is an obsolete synonym provided for BSD compatibility.
	S_IXUSR    = syscall.S_IXUSR  // Execute (for ordinary files) or search (for directories) permission bit for the owner of the file. Usually 0100.
	S_IEXEC    = syscall.S_IEXEC  // Deprecated: S_IEXEC is an obsolete synonym provided for BSD compatibility.
	S_IRWXU    = syscall.S_IRWXU  // This is equivalent to ‘(S_IRUSR | S_IWUSR | S_IXUSR)’.
	S_IRGRP    = syscall.S_IRGRP  // Read permission bit for the group owner of the file. Usually 040.
	S_IWGRP    = syscall.S_IWGRP  // Write permission bit for the group owner of the file. Usually 020.
	S_IXGRP    = syscall.S_IXGRP  // Execute or search permission bit for the group owner of the file. Usually 010.
	S_IRWXG    = syscall.S_IRWXG  // This is equivalent to ‘(S_IRGRP | S_IWGRP | S_IXGRP)’.
	S_IROTH    = syscall.S_IROTH  // Read permission bit for other users. Usually 04.
	S_IWOTH    = syscall.S_IWOTH  // Write permission bit for other users. Usually 02.
	S_IXOTH    = syscall.S_IXOTH  // Execute or search permission bit for other users. Usually 01.
	S_IRWXO    = syscall.S_IRWXO  // This is equivalent to ‘(S_IROTH | S_IWOTH | S_IXOTH)’.
	S_ISUID    = syscall.S_ISUID  // This is the set-user-ID on execute bit, usually 04000. See How Change Persona.
	S_ISGID    = syscall.S_ISGID  // This is the set-group-ID on execute bit, usually 02000. See How Change Persona.
	S_ISVTX    = syscall.S_ISVTX  // This is the sticky bit, usually 01000.
	FP_SPECIAL = 1
)

The Mode Bits for Access Permission The file mode, stored in the st_mode field of the file attributes, contains two kinds of information: the file type code, and the access permission bits. This section discusses only the access permission bits, which control who can read or write the file. See Testing File Type, for information about the file type code. All the symbols listed in this section are defined in the header file sys/stat.h. These symbolic constants are defined for the file mode bits that control access permission for the file:

View Source 
const (
	S_IFMT   = syscall.S_IFMT   // [XSI] type of file mask
	S_IFIFO  = syscall.S_IFIFO  // [XSI] named pipe (fifo)
	S_IFCHR  = syscall.S_IFCHR  // [XSI] character special
	S_IFDIR  = syscall.S_IFDIR  // [XSI] directory
	S_IFBLK  = syscall.S_IFBLK  // [XSI] block special
	S_IFREG  = syscall.S_IFREG  // [XSI] regular
	S_IFLNK  = syscall.S_IFLNK  // [XSI] symbolic link
	S_IFSOCK = syscall.S_IFSOCK // [XSI] socket
)
View Source 
const (
	MFD_ALLOW_SEALING = 0x2
	MFD_CLOEXEC       = 0x1
	MFD_HUGETLB       = 0x4
	MFD_HUGE_16GB     = -0x78000000
	MFD_HUGE_16MB     = 0x60000000
	MFD_HUGE_1GB      = 0x78000000
	MFD_HUGE_1MB      = 0x50000000
	MFD_HUGE_256MB    = 0x70000000
	MFD_HUGE_2GB      = 0x7c000000
	MFD_HUGE_2MB      = 0x54000000
	MFD_HUGE_32MB     = 0x64000000
	MFD_HUGE_512KB    = 0x4c000000
	MFD_HUGE_512MB    = 0x74000000
	MFD_HUGE_64KB     = 0x40000000
	MFD_HUGE_8MB      = 0x5c000000
	MFD_HUGE_MASK     = 0x3f
	MFD_HUGE_SHIFT    = 0x1a
	MCL_CURRENT       = syscall.MCL_CURRENT
	MCL_FUTURE        = syscall.MCL_FUTURE
	MADV_DONTNEED     = syscall.MADV_DONTNEED
	MADV_NORMAL       = syscall.MADV_NORMAL
	MADV_RANDOM       = syscall.MADV_RANDOM
	MADV_SEQUENTIAL   = syscall.MADV_SEQUENTIAL
	MADV_WILLNEED     = syscall.MADV_WILLNEED
	MAP_ANON          = syscall.MAP_ANON // Don't use a file.
	MAP_ANONYMOUS     = syscall.MAP_ANON // Don't use a file.
	MAP_FILE          = syscall.MAP_FILE
	MAP_FIXED         = syscall.MAP_FIXED // Interpret address exactly.
	MAP_NORESERVE     = syscall.MAP_NORESERVE
	MAP_PRIVATE       = syscall.MAP_PRIVATE // Changes are private.
	MAP_SHARED        = syscall.MAP_SHARED  // Share changes.
	MS_ASYNC          = syscall.MS_ASYNC    // Perform synchronous page faults for the mapping.
	MS_INVALIDATE     = syscall.MS_INVALIDATE
	MS_SYNC           = syscall.MS_SYNC
	NAME_MAX          = syscall.NAME_MAX
)
View Source 
const (
	F_GETFD    = syscall.F_GETFD
	F_SETFD    = syscall.F_SETFD
	FD_CLOEXEC = syscall.FD_CLOEXEC
)

File Fcntl

View Source 
const (
	MADV_HUGEPAGE    = syscall.MADV_HUGEPAGE
	MADV_HWPOISON    = syscall.MADV_HWPOISON
	MADV_MERGEABLE   = syscall.MADV_MERGEABLE
	MADV_NOHUGEPAGE  = syscall.MADV_NOHUGEPAGE
	MADV_DOFORK      = syscall.MADV_DOFORK
	MADV_DONTFORK    = syscall.MADV_DONTFORK
	MADV_REMOVE      = syscall.MADV_REMOVE
	MADV_UNMERGEABLE = syscall.MADV_UNMERGEABLE
	MAP_32BIT        = syscall.MAP_32BIT
	MAP_DENYWRITE    = syscall.MAP_DENYWRITE
	MAP_EXECUTABLE   = syscall.MAP_EXECUTABLE
	MAP_GROWSDOWN    = syscall.MAP_GROWSDOWN
	MAP_HUGETLB      = syscall.MAP_HUGETLB
	MAP_LOCKED       = syscall.MAP_LOCKED
	MAP_NONBLOCK     = syscall.MAP_NONBLOCK
	MAP_POPULATE     = syscall.MAP_POPULATE
	MAP_STACK        = syscall.MAP_STACK
	MAP_TYPE         = syscall.MAP_TYPE
	MS_ACTIVE        = syscall.MS_ACTIVE
	MS_I_VERSION     = syscall.MS_I_VERSION
	MS_KERNMOUNT     = syscall.MS_KERNMOUNT
	MS_MANDLOCK      = syscall.MS_MANDLOCK
	MS_MGC_MSK       = syscall.MS_MGC_MSK
	MS_MGC_VAL       = syscall.MS_MGC_VAL
	MS_MOVE          = syscall.MS_MOVE
	MS_NOATIME       = syscall.MS_NOATIME
	MS_NODEV         = syscall.MS_NODEV
	MS_NODIRATIME    = syscall.MS_NODIRATIME
	MS_NOEXEC        = syscall.MS_NOEXEC
	MS_NOSUID        = syscall.MS_NOSUID
	MS_NOUSER        = syscall.MS_NOUSER
	MS_POSIXACL      = syscall.MS_POSIXACL
	MS_PRIVATE       = syscall.MS_PRIVATE
	MS_RDONLY        = syscall.MS_RDONLY
	MS_REC           = syscall.MS_REC
	MS_RELATIME      = syscall.MS_RELATIME
	MS_REMOUNT       = syscall.MS_REMOUNT
	MS_RMT_MASK      = syscall.MS_RMT_MASK
	MS_SHARED        = syscall.MS_SHARED
	MS_SILENT        = syscall.MS_SILENT
	MS_SLAVE         = syscall.MS_SLAVE
	MS_STRICTATIME   = syscall.MS_STRICTATIME
	MS_SYNCHRONOUS   = syscall.MS_SYNCHRONOUS
	MS_UNBINDABLE    = syscall.MS_UNBINDABLE
	MS_BIND          = syscall.MS_BIND
	MS_DIRSYNC       = syscall.MS_DIRSYNC
)

Variables

This section is empty.

Functions

func Close 

func Close(fd int) error

Close the file descriptor allocated by shm_open(3) when it is no longer needed.

func ErrnoHelp 

func ErrnoHelp(e syscall.Errno) string

ErrnoHelp returns descriptive messaging for error number e.

func ErrnoName 

func ErrnoName(e syscall.Errno) string

ErrnoName returns the error name for error number e.

func ErrnoString 

func ErrnoString(e syscall.Errno) string

ErrnoString returns the message for error number e.

func Fchmod 

func Fchmod(fd int, mode int) error

Fchmod To change the permissions of a shared memory object.

func Fchown 

func Fchown(fd int, uid int, gid int) error

Fchown To change the ownership of a shared memory object.

func Fcntl 

func Fcntl(fd int, cmd int, arg int) (val int, err error)

Fcntl performs one of the operations described below on the open file descriptor fd. The operation is determined by cmd

func FilePermStr 

func FilePermStr(perm ModeT, flags int) string

func Fstat 

func Fstat(fd int, stat *Stat_t) error

Fstat Obtain a stat structure that describes the shared memory object. Among the information returned by this call are the object's size (st_size), permissions (st_mode), owner (st_uid), and group (st_gid).

func Ftruncate 

func Ftruncate(fd int, length int) error

Ftruncate Set the size of the shared memory object. (A newly created shared memory object has a length of zero.)

func Getpagesize 

func Getpagesize() int

Getpagesize The function returns the number of bytes in a memory page, where "page" is a fixed-length block, the unit for memory allocation and file mapping performed by mmap

func Madvise 

func Madvise(b []byte, behav int) error

Madvise This system call is used to give advice or directions to the kernel about the address range beginning at address addr and with size length bytes In most cases, the goal of such advice is to improve system or application performance.

func MemfdCreate 

func MemfdCreate(name string, flags int) (fd int, err error)

MemfdCreate creates an anonymous file and returns a file descriptor that refers to it. The file behaves like a regular file, and so can be modified, truncated, memory-mapped, and so on. However, unlike a regular file, it lives in RAM and has a volatile backing storage. Once all references to the file are dropped, it is automatically released.

NOTE: MacOSx is an Emulation of the original function in Linux 

is made for testing only

func Mlock 

func Mlock(b []byte, size int) error

Mlock lock part of the calling process's virtual address space into RAM, preventing that memory from being paged to the swap area.

func Mlockall 

func Mlockall(flags int) error

Mlockall lock all calling process's virtual address space into RAM, preventing that memory from being paged to the swap area.

func Mmap 

func Mmap(address unsafe.Pointer, length int, prot int, flags int, fd int, offset int64) (data []byte, add uintptr, err error)

Mmap Map the shared memory object into the virtual address space of the calling process. MmapAt has the same parameters as the C mmap implementation where the address is exposed.

func Mprotect 

func Mprotect(b []byte, prot int) error

Mprotect changes the access protections for the calling process's memory pages containing any part of the address range in the interval [addr, addr+len-1]. addr must be aligned to a page boundary.

func Msync 

func Msync(b []byte, flags int) error

Msync flushes changes made to the in-core copy of a file that was mapped into memory using mmap(2) back to the filesystem. Without use of this call, there is no guarantee that changes are written back before munmap(2) is called. To be more precise, the part of the file that corresponds to the memory area starting at addr and having length 'length' is updated.

func Munlock 

func Munlock(b []byte, size int) error

Munlock perform the converse operation, unlocking part of the calling process's virtual address space, so that pages in the specified virtual address range may once more to be swapped out if required by the kernel memory manager.

func Munlockall 

func Munlockall() error

Munlockall perform the converse operation, unlocking all calling process's virtual address space, so that pages in the specified virtual address range may once more to be swapped out if required by the kernel memory manager.

func Munmap 

func Munmap(b []byte) error

Munmap Unmap the shared memory object from the virtual address space of the calling process.

func ShmOpen 

func ShmOpen(name string, oflag int, mode uint32) (fd int, err error)

ShmOpen Create and open a new object, or open an existing object. This is analogous to open. The call returns a file descriptor for use by the other interfaces listed below. 

func ShmUnlink(path string) (err error)

ShmUnlink Remove a shared memory object shmName.

Types

type DevT 

type DevT uint64

type Errno 

type Errno = syscall.Errno

type ModeT 

type ModeT uint32

func (ModeT) S_ISBLK 

func (m ModeT) S_ISBLK() bool

S_ISBLK block special

func (ModeT) S_ISCHR 

func (m ModeT) S_ISCHR() bool

S_ISCHR char special

func (ModeT) S_ISDIR 

func (m ModeT) S_ISDIR() bool

S_ISDIR directory

func (ModeT) S_ISFIFO 

func (m ModeT) S_ISFIFO() bool

S_ISFIFO fifo or socket

func (ModeT) S_ISLNK 

func (m ModeT) S_ISLNK() bool

S_ISLNK symbolic link

func (ModeT) S_ISREG 

func (m ModeT) S_ISREG() bool

S_ISREG regular file

func (ModeT) S_ISSOCK 

func (m ModeT) S_ISSOCK() bool

S_ISSOCK socket

type Stat_t 

type Stat_t struct {
	Dev   DevT
	Ino   uint64
	Nlink uint64
	Mode  ModeT
	Uid   uint32
	Gid   uint32

	Rdev    DevT
	Size    int64
	Blksize int64
	Blocks  int64
	Atim    Timespec
	Mtim    Timespec
	Ctim    Timespec
	// contains filtered or unexported fields
}

func (*Stat_t) DisplayStatInfo 

func (sb *Stat_t) DisplayStatInfo()

type Timespec 

type Timespec struct {
	Sec  int64
	Nsec int64
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.