Source file src/unsafe/unsafe.go
1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 /* 6 Package unsafe contains operations that step around the type safety of Go programs. 7 8 Packages that import unsafe may be non-portable and are not protected by the 9 Go 1 compatibility guidelines. 10 */ 11 package unsafe 12 13 // ArbitraryType is here for the purposes of documentation only and is not actually 14 // part of the unsafe package. It represents the type of an arbitrary Go expression. 15 type ArbitraryType int 16 17 // IntegerType is here for the purposes of documentation only and is not actually 18 // part of the unsafe package. It represents any arbitrary integer type. 19 type IntegerType int 20 21 // Pointer represents a pointer to an arbitrary type. There are four special operations 22 // available for type Pointer that are not available for other types: 23 // - A pointer value of any type can be converted to a Pointer. 24 // - A Pointer can be converted to a pointer value of any type. 25 // - A uintptr can be converted to a Pointer. 26 // - A Pointer can be converted to a uintptr. 27 // 28 // Pointer therefore allows a program to defeat the type system and read and write 29 // arbitrary memory. It should be used with extreme care. 30 // 31 // The following patterns involving Pointer are valid. 32 // Code not using these patterns is likely to be invalid today 33 // or to become invalid in the future. 34 // Even the valid patterns below come with important caveats. 35 // 36 // Running "go vet" can help find uses of Pointer that do not conform to these patterns, 37 // but silence from "go vet" is not a guarantee that the code is valid. 38 // 39 // (1) Conversion of a *T1 to Pointer to *T2. 40 // 41 // Provided that T2 is no larger than T1 and that the two share an equivalent 42 // memory layout, this conversion allows reinterpreting data of one type as 43 // data of another type. An example is the implementation of 44 // math.Float64bits: 45 // 46 // func Float64bits(f float64) uint64 { 47 // return *(*uint64)(unsafe.Pointer(&f)) 48 // } 49 // 50 // (2) Conversion of a Pointer to a uintptr (but not back to Pointer). 51 // 52 // Converting a Pointer to a uintptr produces the memory address of the value 53 // pointed at, as an integer. The usual use for such a uintptr is to print it. 54 // 55 // Conversion of a uintptr back to Pointer is not valid in general. 56 // 57 // A uintptr is an integer, not a reference. 58 // Converting a Pointer to a uintptr creates an integer value 59 // with no pointer semantics. 60 // Even if a uintptr holds the address of some object, 61 // the garbage collector will not update that uintptr's value 62 // if the object moves, nor will that uintptr keep the object 63 // from being reclaimed. 64 // 65 // The remaining patterns enumerate the only valid conversions 66 // from uintptr to Pointer. 67 // 68 // (3) Conversion of a Pointer to a uintptr and back, with arithmetic. 69 // 70 // If p points into an allocated object, it can be advanced through the object 71 // by conversion to uintptr, addition of an offset, and conversion back to Pointer. 72 // 73 // p = unsafe.Pointer(uintptr(p) + offset) 74 // 75 // The most common use of this pattern is to access fields in a struct 76 // or elements of an array: 77 // 78 // // equivalent to f := unsafe.Pointer(&s.f) 79 // f := unsafe.Pointer(uintptr(unsafe.Pointer(&s)) + unsafe.Offsetof(s.f)) 80 // 81 // // equivalent to e := unsafe.Pointer(&x[i]) 82 // e := unsafe.Pointer(uintptr(unsafe.Pointer(&x[0])) + i*unsafe.Sizeof(x[0])) 83 // 84 // It is valid both to add and to subtract offsets from a pointer in this way. 85 // It is also valid to use &^ to round pointers, usually for alignment. 86 // In all cases, the result must continue to point into the original allocated object. 87 // 88 // Unlike in C, it is not valid to advance a pointer just beyond the end of 89 // its original allocation: 90 // 91 // // INVALID: end points outside allocated space. 92 // var s thing 93 // end = unsafe.Pointer(uintptr(unsafe.Pointer(&s)) + unsafe.Sizeof(s)) 94 // 95 // // INVALID: end points outside allocated space. 96 // b := make([]byte, n) 97 // end = unsafe.Pointer(uintptr(unsafe.Pointer(&b[0])) + uintptr(n)) 98 // 99 // Note that both conversions must appear in the same expression, with only 100 // the intervening arithmetic between them: 101 // 102 // // INVALID: uintptr cannot be stored in variable 103 // // before conversion back to Pointer. 104 // u := uintptr(p) 105 // p = unsafe.Pointer(u + offset) 106 // 107 // Note that the pointer must point into an allocated object, so it may not be nil. 108 // 109 // // INVALID: conversion of nil pointer 110 // u := unsafe.Pointer(nil) 111 // p := unsafe.Pointer(uintptr(u) + offset) 112 // 113 // (4) Conversion of a Pointer to a uintptr when calling functions like [syscall.Syscall]. 114 // 115 // The Syscall functions in package syscall pass their uintptr arguments directly 116 // to the operating system, which then may, depending on the details of the call, 117 // reinterpret some of them as pointers. 118 // That is, the system call implementation is implicitly converting certain arguments 119 // back from uintptr to pointer. 120 // 121 // If a pointer argument must be converted to uintptr for use as an argument, 122 // that conversion must appear in the call expression itself: 123 // 124 // syscall.Syscall(SYS_READ, uintptr(fd), uintptr(unsafe.Pointer(p)), uintptr(n)) 125 // 126 // The compiler handles a Pointer converted to a uintptr in the argument list of 127 // a call to a function implemented in assembly by arranging that the referenced 128 // allocated object, if any, is retained and not moved until the call completes, 129 // even though from the types alone it would appear that the object is no longer 130 // needed during the call. 131 // 132 // For the compiler to recognize this pattern, 133 // the conversion must appear in the argument list: 134 // 135 // // INVALID: uintptr cannot be stored in variable 136 // // before implicit conversion back to Pointer during system call. 137 // u := uintptr(unsafe.Pointer(p)) 138 // syscall.Syscall(SYS_READ, uintptr(fd), u, uintptr(n)) 139 // 140 // (5) Conversion of the result of [reflect.Value.Pointer] or [reflect.Value.UnsafeAddr] 141 // from uintptr to Pointer. 142 // 143 // Package reflect's Value methods named Pointer and UnsafeAddr return type uintptr 144 // instead of unsafe.Pointer to keep callers from changing the result to an arbitrary 145 // type without first importing "unsafe". However, this means that the result is 146 // fragile and must be converted to Pointer immediately after making the call, 147 // in the same expression: 148 // 149 // p := (*int)(unsafe.Pointer(reflect.ValueOf(new(int)).Pointer())) 150 // 151 // As in the cases above, it is invalid to store the result before the conversion: 152 // 153 // // INVALID: uintptr cannot be stored in variable 154 // // before conversion back to Pointer. 155 // u := reflect.ValueOf(new(int)).Pointer() 156 // p := (*int)(unsafe.Pointer(u)) 157 // 158 // (6) Conversion of a [reflect.SliceHeader] or [reflect.StringHeader] Data field to or from Pointer. 159 // 160 // As in the previous case, the reflect data structures SliceHeader and StringHeader 161 // declare the field Data as a uintptr to keep callers from changing the result to 162 // an arbitrary type without first importing "unsafe". However, this means that 163 // SliceHeader and StringHeader are only valid when interpreting the content 164 // of an actual slice or string value. 165 // 166 // var s string 167 // hdr := (*reflect.StringHeader)(unsafe.Pointer(&s)) // case 1 168 // hdr.Data = uintptr(unsafe.Pointer(p)) // case 6 (this case) 169 // hdr.Len = n 170 // 171 // In this usage hdr.Data is really an alternate way to refer to the underlying 172 // pointer in the string header, not a uintptr variable itself. 173 // 174 // In general, [reflect.SliceHeader] and [reflect.StringHeader] should be used 175 // only as *reflect.SliceHeader and *reflect.StringHeader pointing at actual 176 // slices or strings, never as plain structs. 177 // A program should not declare or allocate variables of these struct types. 178 // 179 // // INVALID: a directly-declared header will not hold Data as a reference. 180 // var hdr reflect.StringHeader 181 // hdr.Data = uintptr(unsafe.Pointer(p)) 182 // hdr.Len = n 183 // s := *(*string)(unsafe.Pointer(&hdr)) // p possibly already lost 184 type Pointer *ArbitraryType 185 186 // Sizeof takes an expression x of any type and returns the size in bytes 187 // of a hypothetical variable v as if v was declared via var v = x. 188 // The size does not include any memory possibly referenced by x. 189 // For instance, if x is a slice, Sizeof returns the size of the slice 190 // descriptor, not the size of the memory referenced by the slice; 191 // if x is an interface, Sizeof returns the size of the interface value itself, 192 // not the size of the value stored in the interface. 193 // For a struct, the size includes any padding introduced by field alignment. 194 // The return value of Sizeof is a Go constant if the type of the argument x 195 // does not have variable size. 196 // (A type has variable size if it is a type parameter or if it is an array 197 // or struct type with elements of variable size). 198 func Sizeof(x ArbitraryType) uintptr 199 200 // Offsetof returns the offset within the struct of the field represented by x, 201 // which must be of the form structValue.field. In other words, it returns the 202 // number of bytes between the start of the struct and the start of the field. 203 // The return value of Offsetof is a Go constant if the type of the argument x 204 // does not have variable size. 205 // (See the description of [Sizeof] for a definition of variable sized types.) 206 func Offsetof(x ArbitraryType) uintptr 207 208 // Alignof takes an expression x of any type and returns the required alignment 209 // of a hypothetical variable v as if v was declared via var v = x. 210 // It is the largest value m such that the address of v is always zero mod m. 211 // It is the same as the value returned by [reflect.TypeOf](x).Align(). 212 // As a special case, if a variable s is of struct type and f is a field 213 // within that struct, then Alignof(s.f) will return the required alignment 214 // of a field of that type within a struct. This case is the same as the 215 // value returned by [reflect.TypeOf](s.f).FieldAlign(). 216 // The return value of Alignof is a Go constant if the type of the argument 217 // does not have variable size. 218 // (See the description of [Sizeof] for a definition of variable sized types.) 219 func Alignof(x ArbitraryType) uintptr 220 221 // The function Add adds len to ptr and returns the updated pointer 222 // [Pointer](uintptr(ptr) + uintptr(len)). 223 // The len argument must be of integer type or an untyped constant. 224 // A constant len argument must be representable by a value of type int; 225 // if it is an untyped constant it is given type int. 226 // The rules for valid uses of Pointer still apply. 227 func Add(ptr Pointer, len IntegerType) Pointer 228 229 // The function Slice returns a slice whose underlying array starts at ptr 230 // and whose length and capacity are len. 231 // Slice(ptr, len) is equivalent to 232 // 233 // (*[len]ArbitraryType)(unsafe.Pointer(ptr))[:] 234 // 235 // except that, as a special case, if ptr is nil and len is zero, 236 // Slice returns nil. 237 // 238 // The len argument must be of integer type or an untyped constant. 239 // A constant len argument must be non-negative and representable by a value of type int; 240 // if it is an untyped constant it is given type int. 241 // At run time, if len is negative, or if ptr is nil and len is not zero, 242 // a run-time panic occurs. 243 func Slice(ptr *ArbitraryType, len IntegerType) []ArbitraryType 244 245 // SliceData returns a pointer to the underlying array of the argument 246 // slice. 247 // - If cap(slice) > 0, SliceData returns &slice[:1][0]. 248 // - If slice == nil, SliceData returns nil. 249 // - Otherwise, SliceData returns a non-nil pointer to an 250 // unspecified memory address. 251 func SliceData(slice []ArbitraryType) *ArbitraryType 252 253 // String returns a string value whose underlying bytes 254 // start at ptr and whose length is len. 255 // 256 // The len argument must be of integer type or an untyped constant. 257 // A constant len argument must be non-negative and representable by a value of type int; 258 // if it is an untyped constant it is given type int. 259 // At run time, if len is negative, or if ptr is nil and len is not zero, 260 // a run-time panic occurs. 261 // 262 // Since Go strings are immutable, the bytes passed to String 263 // must not be modified as long as the returned string value exists. 264 func String(ptr *byte, len IntegerType) string 265 266 // StringData returns a pointer to the underlying bytes of str. 267 // For an empty string the return value is unspecified, and may be nil. 268 // 269 // Since Go strings are immutable, the bytes returned by StringData 270 // must not be modified. 271 func StringData(str string) *byte 272