package unsafe

Import Path
	unsafe (on go.dev)

Dependency Relation
	imports 0 packages, and imported by 77 packages


Involved Source Files

	
		Package unsafe contains operations that step around the type safety of Go programs.
		
		Packages that import unsafe may be non-portable and are not protected by the
		Go 1 compatibility guidelines.


Package-Level Type Names (total 3)


	/* sort by:  |  */
	
		ArbitraryType is here for the purposes of documentation only and is not actually
		part of the unsafe package. It represents the type of an arbitrary Go expression.


	
		IntegerType is here for the purposes of documentation only and is not actually
		part of the unsafe package. It represents any arbitrary integer type.


	
		Pointer represents a pointer to an arbitrary type. There are four special operations
		available for type Pointer that are not available for other types:
		  - A pointer value of any type can be converted to a Pointer.
		  - A Pointer can be converted to a pointer value of any type.
		  - A uintptr can be converted to a Pointer.
		  - A Pointer can be converted to a uintptr.
		
		Pointer therefore allows a program to defeat the type system and read and write
		arbitrary memory. It should be used with extreme care.
		
		The following patterns involving Pointer are valid.
		Code not using these patterns is likely to be invalid today
		or to become invalid in the future.
		Even the valid patterns below come with important caveats.
		
		Running "go vet" can help find uses of Pointer that do not conform to these patterns,
		but silence from "go vet" is not a guarantee that the code is valid.
		
		(1) Conversion of a *T1 to Pointer to *T2.
		
		Provided that T2 is no larger than T1 and that the two share an equivalent
		memory layout, this conversion allows reinterpreting data of one type as
		data of another type. An example is the implementation of
		math.Float64bits:
		
			func Float64bits(f float64) uint64 {
				return *(*uint64)(unsafe.Pointer(&f))
			}
		
		(2) Conversion of a Pointer to a uintptr (but not back to Pointer).
		
		Converting a Pointer to a uintptr produces the memory address of the value
		pointed at, as an integer. The usual use for such a uintptr is to print it.
		
		Conversion of a uintptr back to Pointer is not valid in general.
		
		A uintptr is an integer, not a reference.
		Converting a Pointer to a uintptr creates an integer value
		with no pointer semantics.
		Even if a uintptr holds the address of some object,
		the garbage collector will not update that uintptr's value
		if the object moves, nor will that uintptr keep the object
		from being reclaimed.
		
		The remaining patterns enumerate the only valid conversions
		from uintptr to Pointer.
		
		(3) Conversion of a Pointer to a uintptr and back, with arithmetic.
		
		If p points into an allocated object, it can be advanced through the object
		by conversion to uintptr, addition of an offset, and conversion back to Pointer.
		
			p = unsafe.Pointer(uintptr(p) + offset)
		
		The most common use of this pattern is to access fields in a struct
		or elements of an array:
		
			// equivalent to f := unsafe.Pointer(&s.f)
			f := unsafe.Pointer(uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f))
		
			// equivalent to e := unsafe.Pointer(&x[i])
			e := unsafe.Pointer(uintptr(unsafe.Pointer(&x[0])) + i*unsafe.Sizeof(x[0]))
		
		It is valid both to add and to subtract offsets from a pointer in this way.
		It is also valid to use &^ to round pointers, usually for alignment.
		In all cases, the result must continue to point into the original allocated object.
		
		Unlike in C, it is not valid to advance a pointer just beyond the end of
		its original allocation:
		
			// INVALID: end points outside allocated space.
			var s thing
			end = unsafe.Pointer(uintptr(unsafe.Pointer(&s)) + unsafe.Sizeof(s))
		
			// INVALID: end points outside allocated space.
			b := make([]byte, n)
			end = unsafe.Pointer(uintptr(unsafe.Pointer(&b[0])) + uintptr(n))
		
		Note that both conversions must appear in the same expression, with only
		the intervening arithmetic between them:
		
			// INVALID: uintptr cannot be stored in variable
			// before conversion back to Pointer.
			u := uintptr(p)
			p = unsafe.Pointer(u + offset)
		
		Note that the pointer must point into an allocated object, so it may not be nil.
		
			// INVALID: conversion of nil pointer
			u := unsafe.Pointer(nil)
			p := unsafe.Pointer(uintptr(u) + offset)
		
		(4) Conversion of a Pointer to a uintptr when calling functions like [syscall.Syscall].
		
		The Syscall functions in package syscall pass their uintptr arguments directly
		to the operating system, which then may, depending on the details of the call,
		reinterpret some of them as pointers.
		That is, the system call implementation is implicitly converting certain arguments
		back from uintptr to pointer.
		
		If a pointer argument must be converted to uintptr for use as an argument,
		that conversion must appear in the call expression itself:
		
			syscall.Syscall(SYS_READ, uintptr(fd), uintptr(unsafe.Pointer(p)), uintptr(n))
		
		The compiler handles a Pointer converted to a uintptr in the argument list of
		a call to a function implemented in assembly by arranging that the referenced
		allocated object, if any, is retained and not moved until the call completes,
		even though from the types alone it would appear that the object is no longer
		needed during the call.
		
		For the compiler to recognize this pattern,
		the conversion must appear in the argument list:
		
			// INVALID: uintptr cannot be stored in variable
			// before implicit conversion back to Pointer during system call.
			u := uintptr(unsafe.Pointer(p))
			syscall.Syscall(SYS_READ, uintptr(fd), u, uintptr(n))
		
		(5) Conversion of the result of [reflect.Value.Pointer] or [reflect.Value.UnsafeAddr]
		from uintptr to Pointer.
		
		Package reflect's Value methods named Pointer and UnsafeAddr return type uintptr
		instead of unsafe.Pointer to keep callers from changing the result to an arbitrary
		type without first importing "unsafe". However, this means that the result is
		fragile and must be converted to Pointer immediately after making the call,
		in the same expression:
		
			p := (*int)(unsafe.Pointer(reflect.ValueOf(new(int)).Pointer()))
		
		As in the cases above, it is invalid to store the result before the conversion:
		
			// INVALID: uintptr cannot be stored in variable
			// before conversion back to Pointer.
			u := reflect.ValueOf(new(int)).Pointer()
			p := (*int)(unsafe.Pointer(u))
		
		(6) Conversion of a [reflect.SliceHeader] or [reflect.StringHeader] Data field to or from Pointer.
		
		As in the previous case, the reflect data structures SliceHeader and StringHeader
		declare the field Data as a uintptr to keep callers from changing the result to
		an arbitrary type without first importing "unsafe". However, this means that
		SliceHeader and StringHeader are only valid when interpreting the content
		of an actual slice or string value.
		
			var s string
			hdr := (*reflect.StringHeader)(unsafe.Pointer(&s)) // case 1
			hdr.Data = uintptr(unsafe.Pointer(p))              // case 6 (this case)
			hdr.Len = n
		
		In this usage hdr.Data is really an alternate way to refer to the underlying
		pointer in the string header, not a uintptr variable itself.
		
		In general, [reflect.SliceHeader] and [reflect.StringHeader] should be used
		only as *reflect.SliceHeader and *reflect.StringHeader pointing at actual
		slices or strings, never as plain structs.
		A program should not declare or allocate variables of these struct types.
		
			// INVALID: a directly-declared header will not hold Data as a reference.
			var hdr reflect.StringHeader
			hdr.Data = uintptr(unsafe.Pointer(p))
			hdr.Len = n
			s := *(*string)(unsafe.Pointer(&hdr)) // p possibly already lost

		
			func internal/abi.NoEscape(p Pointer) Pointer
			func internal/abi.(*RegArgs).IntRegArgAddr(reg int, argSize uintptr) Pointer
			func internal/runtime/atomic.Loadp(ptr Pointer) Pointer
			func internal/runtime/atomic.(*UnsafePointer).Load() Pointer
			func reflect.Value.UnsafePointer() Pointer
			func sync/atomic.LoadPointer(addr *Pointer) (val Pointer)
			func sync/atomic.SwapPointer(addr *Pointer, new Pointer) (old Pointer)
		
			func internal/abi.NoEscape(p Pointer) Pointer
			func internal/asan.Read(addr Pointer, len uintptr)
			func internal/asan.Write(addr Pointer, len uintptr)
			func internal/coverage/rtcov.AddMeta(p Pointer, dlen uint32, hash [16]byte, pkgpath string, pkgid int, cmode uint8, cgran uint8) uint32
			func internal/msan.Free(addr Pointer, sz uintptr)
			func internal/msan.Malloc(addr Pointer, sz uintptr)
			func internal/msan.Move(dst, src Pointer, sz uintptr)
			func internal/msan.Read(addr Pointer, sz uintptr)
			func internal/msan.Write(addr Pointer, sz uintptr)
			func internal/race.Acquire(addr Pointer)
			func internal/race.Read(addr Pointer)
			func internal/race.ReadRange(addr Pointer, len int)
			func internal/race.Release(addr Pointer)
			func internal/race.ReleaseMerge(addr Pointer)
			func internal/race.Write(addr Pointer)
			func internal/race.WriteRange(addr Pointer, len int)
			func internal/runtime/atomic.Casp1(ptr *Pointer, old, new Pointer) bool
			func internal/runtime/atomic.Casp1(ptr *Pointer, old, new Pointer) bool
			func internal/runtime/atomic.Loadp(ptr Pointer) Pointer
			func internal/runtime/atomic.StorepNoWB(ptr Pointer, val Pointer)
			func internal/runtime/atomic.StorepNoWB(ptr Pointer, val Pointer)
			func internal/runtime/atomic.(*UnsafePointer).CompareAndSwap(old, new Pointer) bool
			func internal/runtime/atomic.(*UnsafePointer).CompareAndSwapNoWB(old, new Pointer) bool
			func internal/runtime/atomic.(*UnsafePointer).Store(value Pointer)
			func internal/runtime/atomic.(*UnsafePointer).StoreNoWB(value Pointer)
			func reflect.NewAt(typ reflect.Type, p Pointer) reflect.Value
			func reflect.SliceAt(typ reflect.Type, p Pointer, n int) reflect.Value
			func reflect.Value.SetPointer(x Pointer)
			func runtime.SetCgoTraceback(version int, traceback, context, symbolizer Pointer)
			func sync/atomic.CompareAndSwapPointer(addr *Pointer, old, new Pointer) (swapped bool)
			func sync/atomic.CompareAndSwapPointer(addr *Pointer, old, new Pointer) (swapped bool)
			func sync/atomic.LoadPointer(addr *Pointer) (val Pointer)
			func sync/atomic.StorePointer(addr *Pointer, val Pointer)
			func sync/atomic.StorePointer(addr *Pointer, val Pointer)
			func sync/atomic.SwapPointer(addr *Pointer, new Pointer) (old Pointer)
			func sync/atomic.SwapPointer(addr *Pointer, new Pointer) (old Pointer)




Package-Level Functions (total 8)


	
		The function Add adds len to ptr and returns the updated pointer
		[Pointer](uintptr(ptr) + uintptr(len)).
		The len argument must be of integer type or an untyped constant.
		A constant len argument must be representable by a value of type int;
		if it is an untyped constant it is given type int.
		The rules for valid uses of Pointer still apply.


	
		Alignof takes an expression x of any type and returns the required alignment
		of a hypothetical variable v as if v was declared via var v = x.
		It is the largest value m such that the address of v is always zero mod m.
		It is the same as the value returned by [reflect.TypeOf](x).Align().
		As a special case, if a variable s is of struct type and f is a field
		within that struct, then Alignof(s.f) will return the required alignment
		of a field of that type within a struct. This case is the same as the
		value returned by [reflect.TypeOf](s.f).FieldAlign().
		The return value of Alignof is a Go constant if the type of the argument
		does not have variable size.
		(See the description of [Sizeof] for a definition of variable sized types.)


	
		Offsetof returns the offset within the struct of the field represented by x,
		which must be of the form structValue.field. In other words, it returns the
		number of bytes between the start of the struct and the start of the field.
		The return value of Offsetof is a Go constant if the type of the argument x
		does not have variable size.
		(See the description of [Sizeof] for a definition of variable sized types.)


	
		Sizeof takes an expression x of any type and returns the size in bytes
		of a hypothetical variable v as if v was declared via var v = x.
		The size does not include any memory possibly referenced by x.
		For instance, if x is a slice, Sizeof returns the size of the slice
		descriptor, not the size of the memory referenced by the slice;
		if x is an interface, Sizeof returns the size of the interface value itself,
		not the size of the value stored in the interface.
		For a struct, the size includes any padding introduced by field alignment.
		The return value of Sizeof is a Go constant if the type of the argument x
		does not have variable size.
		(A type has variable size if it is a type parameter or if it is an array
		or struct type with elements of variable size).


	
		The function Slice returns a slice whose underlying array starts at ptr
		and whose length and capacity are len.
		Slice(ptr, len) is equivalent to
		
			(*[len]ArbitraryType)(unsafe.Pointer(ptr))[:]
		
		except that, as a special case, if ptr is nil and len is zero,
		Slice returns nil.
		
		The len argument must be of integer type or an untyped constant.
		A constant len argument must be non-negative and representable by a value of type int;
		if it is an untyped constant it is given type int.
		At run time, if len is negative, or if ptr is nil and len is not zero,
		a run-time panic occurs.


	
		SliceData returns a pointer to the underlying array of the argument
		slice.
		  - If cap(slice) > 0, SliceData returns &slice[:1][0].
		  - If slice == nil, SliceData returns nil.
		  - Otherwise, SliceData returns a non-nil pointer to an
		    unspecified memory address.


	
		String returns a string value whose underlying bytes
		start at ptr and whose length is len.
		
		The len argument must be of integer type or an untyped constant.
		A constant len argument must be non-negative and representable by a value of type int;
		if it is an untyped constant it is given type int.
		At run time, if len is negative, or if ptr is nil and len is not zero,
		a run-time panic occurs.
		
		Since Go strings are immutable, the bytes passed to String
		must not be modified as long as the returned string value exists.


	
		StringData returns a pointer to the underlying bytes of str.
		For an empty string the return value is unspecified, and may be nil.
		
		Since Go strings are immutable, the bytes returned by StringData
		must not be modified.