16 Unsafe Operations

▼ |  | The Racket Reference

1 | Language Model
2 | Syntactic Forms
3 | Datatypes
4 | Structures
5 | Classes and Objects
6 | Units
7 | Contracts
8 | Pattern Matching
9 | Control Flow
10 | Concurrency and Parallelism
11 | Macros
12 | Input and Output
13 | Reflection and Security
14 | Operating System
15 | Memory Management
16 | Unsafe Operations
17 | Running Racket
| Bibliography
| Index

► | 16 | Unsafe Operations

16.1 | Unsafe Numeric Operations
16.2 | Unsafe Data Extraction
16.3 | Unsafe Extflonum Operations

On this page:

16.1`` Unsafe Numeric Operations
unsafe-fx+
unsafe-fx-
unsafe-fx*
unsafe-fxquotient
unsafe-fxremainder
unsafe-fxmodulo
unsafe-fxabs
unsafe-fxand
unsafe-fxior
unsafe-fxxor
unsafe-fxnot
unsafe-fxlshift
unsafe-fxrshift
unsafe-fx=
unsafe-fx<
unsafe-fx>
unsafe-fx<=
unsafe-fx>=
unsafe-fxmin
unsafe-fxmax
unsafe-fl+
unsafe-fl-
unsafe-fl*
unsafe-fl/
unsafe-flabs
unsafe-fl=
unsafe-fl<
unsafe-fl>
unsafe-fl<=
unsafe-fl>=
unsafe-flmin
unsafe-flmax
unsafe-flround
unsafe-flfloor
unsafe-flceiling
unsafe-fltruncate
unsafe-flsin
unsafe-flcos
unsafe-fltan
unsafe-flasin
unsafe-flacos
unsafe-flatan
unsafe-fllog
unsafe-flexp
unsafe-flsqrt
unsafe-flexpt
unsafe-make-flrectangular
unsafe-flreal-part
unsafe-flimag-part
unsafe-fx->fl
unsafe-fl->fx
16.2`` Unsafe Data Extraction
unsafe-car
unsafe-cdr
unsafe-mcar
unsafe-mcdr
unsafe-set-mcar!
unsafe-set-mcdr!
unsafe-cons-list
unsafe-list-ref
unsafe-list-tail
unsafe-unbox
unsafe-set-box!
unsafe-unbox*
unsafe-set-box*!
unsafe-box*-cas!
unsafe-vector-length
unsafe-vector-ref
unsafe-vector-set!
unsafe-vector*-length
unsafe-vector*-ref
unsafe-vector*-set!
unsafe-string-length
unsafe-string-ref
unsafe-string-set!
unsafe-bytes-length
unsafe-bytes-ref
unsafe-bytes-set!
unsafe-flvector-length
unsafe-flvector-ref
unsafe-flvector-set!
unsafe-f64vector-ref
unsafe-f64vector-set!
unsafe-s16vector-ref
unsafe-s16vector-set!
unsafe-u16vector-ref
unsafe-u16vector-set!
unsafe-struct-ref
unsafe-struct-set!
unsafe-struct*-ref
unsafe-struct*-set!
16.3`` Unsafe Extflonum Operations
unsafe-extfl+
unsafe-extfl-
unsafe-extfl*
unsafe-extfl/
unsafe-extflabs
unsafe-extfl=
unsafe-extfl<
unsafe-extfl>
unsafe-extfl<=
unsafe-extfl>=
unsafe-extflmin
unsafe-extflmax
unsafe-extflround
unsafe-extflfloor
unsafe-extflceiling
unsafe-extfltruncate
unsafe-extflsin
unsafe-extflcos
unsafe-extfltan
unsafe-extflasin
unsafe-extflacos
unsafe-extflatan
unsafe-extfllog
unsafe-extflexp
unsafe-extflsqrt
unsafe-extflexpt
unsafe-fx->extfl
unsafe-extfl->fx
unsafe-extflvector-length
unsafe-extflvector-ref
unsafe-extflvector-set!

top ← prev up next →

### 16`` Unsafe Operations

(require racket/unsafe/ops)

All functions and forms provided by racket/base and racket check their arguments to ensure that the arguments conform to contracts and other constraints. For example, vector-ref checks its arguments to ensure that the first argument is a vector, that the second argument is an exact integer, and that the second argument is between 0 and one less than the vector’s length, inclusive.

Functions provided by racket/unsafe/ops are unsafe. They have certain constraints, but the constraints are not checked, which allows the system to generate and execute faster code. If arguments violate an unsafe function’s constraints, the function’s behavior and result is unpredictable, and the entire system can crash or become corrupted.

All of the exported bindings of racket/unsafe/ops are protected in the sense of protect-out, so access to unsafe operations can be prevented by adjusting the code inspector (see Code Inspectors).

#### 16.1`` Unsafe Numeric Operations

> procedure (unsafe-fx+ a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx- a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx* a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxquotient a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxremainder a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxmodulo a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxabs a) → fixnum?
> a : fixnum?

For fixnums: Like +, -, *, quotient, remainder, modulo, and abs, but constrained to consume fixnums and produce a fixnum result. The mathematical operation on a and b must be representable as a fixnum. In the case of unsafe-fxquotient, unsafe-fxremainder, and unsafe-fxmodulo, b must not be 0.

> procedure (unsafe-fxand a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxior a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxxor a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxnot a) → fixnum?
> a : fixnum?
> procedure (unsafe-fxlshift a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxrshift a b) → fixnum?
> a : fixnum?
> b : fixnum?

For fixnums: Like bitwise-and, bitwise-ior, bitwise-xor, bitwise-not, and arithmetic-shift, but constrained to consume fixnums; the result is always a fixnum. The unsafe-fxlshift and unsafe-fxrshift operations correspond to arithmetic-shift, but require non-negative arguments; unsafe-fxlshift is a positive (i.e., left) shift, and unsafe-fxrshift is a negative (i.e., right) shift, where the number of bits to shift must be less than the number of bits used to represent a fixnum. In the case of unsafe-fxlshift, bits in the result beyond the number of bits used to represent a fixnum are effectively replaced with a copy of the high bit.

> procedure (unsafe-fx= a b) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx< a b) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx> a b) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx<= a b) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fx>= a b) → boolean?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxmin a b) → fixnum?
> a : fixnum?
> b : fixnum?
> procedure (unsafe-fxmax a b) → fixnum?
> a : fixnum?
> b : fixnum?

For fixnums: Like =, <, >, <=, >=, min, and max, but constrained to consume fixnums.

> procedure (unsafe-fl+ a b) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl- a b) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl* a b) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl/ a b) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-flabs a) → flonum?
> a : flonum?

For flonums: Unchecked versions of fl+, fl-, fl*, fl/, and flabs.

> procedure (unsafe-fl= a b) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl< a b) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl> a b) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl<= a b) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-fl>= a b) → boolean?
> a : flonum?
> b : flonum?
> procedure (unsafe-flmin a b) → flonum?
> a : flonum?
> b : flonum?
> procedure (unsafe-flmax a b) → flonum?
> a : flonum?
> b : flonum?

For flonums: Unchecked versions of fl=, fl<, fl>, fl<=, fl>=, flmin, and flmax.

> procedure (unsafe-flround a) → flonum?
> a : flonum?
> procedure (unsafe-flfloor a) → flonum?
> a : flonum?
> procedure (unsafe-flceiling a) → flonum?
> a : flonum?
> procedure (unsafe-fltruncate a) → flonum?
> a : flonum?

For flonums: Unchecked (potentially) versions of flround, flfloor, flceiling, and fltruncate. Currently, these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-flsin a) → flonum?
> a : flonum?
> procedure (unsafe-flcos a) → flonum?
> a : flonum?
> procedure (unsafe-fltan a) → flonum?
> a : flonum?
> procedure (unsafe-flasin a) → flonum?
> a : flonum?
> procedure (unsafe-flacos a) → flonum?
> a : flonum?
> procedure (unsafe-flatan a) → flonum?
> a : flonum?
> procedure (unsafe-fllog a) → flonum?
> a : flonum?
> procedure (unsafe-flexp a) → flonum?
> a : flonum?
> procedure (unsafe-flsqrt a) → flonum?
> a : flonum?
> procedure (unsafe-flexpt a b) → flonum?
> a : flonum?
> b : flonum?

For flonums: Unchecked (potentially) versions of flsin, flcos, fltan, flasin, flacos, flatan, fllog, flexp, flsqrt, and flexpt. Currently, some of these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-make-flrectangular a b)
> → (and/c complex? inexact? (not/c real?))
> a : flonum?
> b : flonum?
> procedure (unsafe-flreal-part a) → flonum?
> a : (and/c complex? inexact? (not/c real?))
> procedure (unsafe-flimag-part a) → flonum?
> a : (and/c complex? inexact? (not/c real?))

For flonums: Unchecked versions of make-flrectangular, flreal-part, and flimag-part.

> procedure (unsafe-fx->fl a) → flonum?
> a : fixnum?
> procedure (unsafe-fl->fx a) → fixnum?
> a : flonum?

Unchecked conversion of a fixnum to an integer flonum and vice versa. These are similar to the safe bindings ->fl and fl->exact-integer, but further constrained to consume or produce a fixnum.

#### 16.2`` Unsafe Data Extraction

> procedure (unsafe-car p) → any/c
> p : pair?
> procedure (unsafe-cdr p) → any/c
> p : pair?
> procedure (unsafe-mcar p) → any/c
> p : mpair?
> procedure (unsafe-mcdr p) → any/c
> p : mpair?
> procedure (unsafe-set-mcar! p v) → void?
> p : mpair?
> v : any/c
> procedure (unsafe-set-mcdr! p v) → void?
> p : mpair?
> v : any/c

Unsafe variants of car, cdr, mcar, mcdr, set-mcar!, and set-mcdr!.

> procedure (unsafe-cons-list v rest) → (and/c pair? list?)
> v : any/c
> rest : list?

Unsafe variant of cons that produces a pair that claims to be a list—without checking whether rest is a list.

> procedure (unsafe-list-ref lst pos) → any/c
> lst : pair?
> pos : (and/c exact-nonnegative-integer? fixnum?)
> procedure (unsafe-list-tail lst pos) → any/c
> lst : any/c
> pos : (and/c exact-nonnegative-integer? fixnum?)

Unsafe variants of list-ref and list-tail, where pos must be a fixnum, and lst must start with at least (add1 pos) (for unsafe-list-ref) or pos (for unsafe-list-tail) pairs.

> procedure (unsafe-unbox b) → fixnum?
> b : box?
> procedure (unsafe-set-box! b k) → void?
> b : box?
> k : fixnum?
> procedure (unsafe-unbox* v) → any/c
> v : (and/c box? (not/c impersonator?))
> procedure (unsafe-set-box*! v val) → void?
> v : (and/c box? (not/c impersonator?))
> val : any/c

Unsafe versions of unbox and set-box!, where the box* variants can be faster but do not work on impersonators.

> procedure (unsafe-box*-cas! loc old new) → boolean?
> loc : box?
> old : any/c
> new : any/c

Unsafe version of box-cas!. Like unsafe-set-box*!, it does not work on impersonators.

> procedure (unsafe-vector-length v) → fixnum?
> v : vector?
> procedure (unsafe-vector-ref v k) → any/c
> v : vector?
> k : fixnum?
> procedure (unsafe-vector-set! v k val) → void?
> v : vector?
> k : fixnum?
> val : any/c
> procedure (unsafe-vector*-length v) → fixnum?
> v : (and/c vector? (not/c impersonator?))
> procedure (unsafe-vector*-ref v k) → any/c
> v : (and/c vector? (not/c impersonator?))
> k : fixnum?
> procedure (unsafe-vector*-set! v k val) → void?
> v : (and/c vector? (not/c impersonator?))
> k : fixnum?
> val : any/c

Unsafe versions of vector-length, vector-ref, and vector-set!, where the vector* variants can be faster but do not work on impersonators.

A vector’s size can never be larger than a fixnum, so even vector-length always returns a fixnum.

> procedure (unsafe-string-length str) → fixnum?
> str : string?
> procedure (unsafe-string-ref str k)
> → (and/c char? (lambda (ch) (<= 0 (char->integer ch) 255)))
> str : string?
> k : fixnum?
> procedure (unsafe-string-set! str k ch) → void?
> str : (and/c string? (not/c immutable?))
> k : fixnum?
> ch : char?

Unsafe versions of string-length, string-ref, and string-set!. The unsafe-string-ref procedure can be used only when the result will be a Latin-1 character. A string’s size can never be larger than a fixnum (so even string-length always returns a fixnum).

> procedure (unsafe-bytes-length bstr) → fixnum?
> bstr : bytes?
> procedure (unsafe-bytes-ref bstr k) → byte?
> bstr : bytes?
> k : fixnum?
> procedure (unsafe-bytes-set! bstr k b) → void?
> bstr : (and/c bytes? (not/c immutable?))
> k : fixnum?
> b : byte?

Unsafe versions of bytes-length, bytes-ref, and bytes-set!. A bytes’s size can never be larger than a fixnum (so even bytes-length always returns a fixnum).

> procedure (unsafe-flvector-length v) → fixnum?
> v : flvector?
> procedure (unsafe-flvector-ref v k) → any/c
> v : flvector?
> k : fixnum?
> procedure (unsafe-flvector-set! v k x) → void?
> v : flvector?
> k : fixnum?
> x : flonum?

Unsafe versions of flvector-length, flvector-ref, and flvector-set!. A flvector’s size can never be larger than a fixnum (so even flvector-length always returns a fixnum).

> procedure (unsafe-f64vector-ref vec k) → flonum?
> vec : f64vector?
> k : fixnum?
> procedure (unsafe-f64vector-set! vec k n) → void?
> vec : f64vector?
> k : fixnum?
> n : flonum?

Unsafe versions of f64vector-ref and f64vector-set!.

> procedure (unsafe-s16vector-ref vec k) → (integer-in -32768 32767)
> vec : s16vector?
> k : fixnum?
> procedure (unsafe-s16vector-set! vec k n) → void?
> vec : s16vector?
> k : fixnum?
> n : (integer-in -32768 32767)

Unsafe versions of s16vector-ref and s16vector-set!.

> procedure (unsafe-u16vector-ref vec k) → (integer-in 0 65535)
> vec : u16vector?
> k : fixnum?
> procedure (unsafe-u16vector-set! vec k n) → void?
> vec : u16vector?
> k : fixnum?
> n : (integer-in 0 65535)

Unsafe versions of u16vector-ref and u16vector-set!.

> procedure (unsafe-struct-ref v k) → any/c
> v : any/c
> k : fixnum?
> procedure (unsafe-struct-set! v k val) → void?
> v : any/c
> k : fixnum?
> val : any/c
> procedure (unsafe-struct*-ref v k) → any/c
> v : (not/c impersonator?)
> k : fixnum?
> procedure (unsafe-struct*-set! v k val) → void?
> v : (not/c impersonator?)
> k : fixnum?
> val : any/c

Unsafe field access and update for an instance of a structure type, where the struct* variants can be faster but do not work on impersonators. The index k must be between 0 (inclusive) and the number of fields in the structure (exclusive). In the case of unsafe-struct-set!, the field must be mutable.

#### 16.3`` Unsafe Extflonum Operations

> procedure (unsafe-extfl+ a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl- a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl* a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl/ a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extflabs a) → extflonum?
> a : extflonum?

Unchecked versions of extfl+, extfl-, extfl*, extfl/, and extflabs.

> procedure (unsafe-extfl= a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl< a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl> a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl<= a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extfl>= a b) → boolean?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extflmin a b) → extflonum?
> a : extflonum?
> b : extflonum?
> procedure (unsafe-extflmax a b) → extflonum?
> a : extflonum?
> b : extflonum?

Unchecked versions of extfl=, extfl<, extfl>, extfl<=, extfl>=, extflmin, and extflmax.

> procedure (unsafe-extflround a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflfloor a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflceiling a) → extflonum?
> a : extflonum?
> procedure (unsafe-extfltruncate a) → extflonum?
> a : extflonum?

Unchecked (potentially) versions of extflround, extflfloor, extflceiling, and extfltruncate. Currently, these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-extflsin a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflcos a) → extflonum?
> a : extflonum?
> procedure (unsafe-extfltan a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflasin a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflacos a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflatan a) → extflonum?
> a : extflonum?
> procedure (unsafe-extfllog a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflexp a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflsqrt a) → extflonum?
> a : extflonum?
> procedure (unsafe-extflexpt a b) → extflonum?
> a : extflonum?
> b : extflonum?

Unchecked (potentially) versions of extflsin, extflcos, extfltan, extflasin, extflacos, extflatan, extfllog, extflexp, extflsqrt, and extflexpt. Currently, some of these bindings are simply aliases for the corresponding safe bindings.

> procedure (unsafe-fx->extfl a) → extflonum?
> a : fixnum?
> procedure (unsafe-extfl->fx a) → fixnum?
> a : extflonum?

Unchecked conversion of a fixnum to an integer extflonum and vice versa. These are similar to the safe bindings ->extfl and extfl->exact-integer, but further constrained to consume or produce a fixnum.

> procedure (unsafe-extflvector-length v) → fixnum?
> v : extflvector?
> procedure (unsafe-extflvector-ref v k) → any/c
> v : extflvector?
> k : fixnum?
> procedure (unsafe-extflvector-set! v k x) → void?
> v : extflvector?
> k : fixnum?
> x : extflonum?

Unchecked versions of extflvector-length, extflvector-ref, and extflvector-set!. A extflvector’s size can never be larger than a fixnum (so even extflvector-length always returns a fixnum).
top ← prev up next →