Chapter 25 Unsafe code

125. Unsafe code

2An implementation that does not support unsafe code is required to diagnose any usage of the keyword

3unsafe.

4The remainder of this clause, including all of its subclauses, is conditionally normative.

5[Note: The core C# language, as defined in the preceding clauses, differs notably from C and C++ in its

6omission of pointers as a data type. Instead, C# provides references and the ability to create objects that are

7managed by a garbage collector. This design, coupled with other features, makes C# a much safer language

8than C or C++. In the core C# language it is simply not possible to have an uninitialized variable, a

9“dangling” pointer, or an expression that indexes an array beyond its bounds. Whole categories of bugs that

10routinely plague C and C++ programs are thus eliminated.

11While practically every pointer type construct in C or C++ has a reference type counterpart in C#,

12nonetheless, there are situations where access to pointer types becomes a necessity. For example, interfacing

13with the underlying operating system, accessing a memory-mapped device, or implementing a time-critical

14algorithm might not be possible or practical without access to pointers. To address this need, C# provides the

15ability to write unsafe code.

16In unsafe code it is possible to declare and operate on pointers, to perform conversions between pointers and

17integral types, to take the address of variables, and so forth. In a sense, writing unsafe code is much like

18writing C code within a C# program.

19Unsafe code is in fact a “safe” feature from the perspective of both developers and users. Unsafe code shall

20be clearly marked with the modifier unsafe, so developers can’t possibly use unsafe features accidentally,

21and the execution engine works to ensure that unsafe code cannot be executed in an untrusted environment.

22end note]

2325.1 Unsafe contexts

24The unsafe features of C# are available only in unsafe contexts. An unsafe context is introduced by including

25an unsafe modifier in the declaration of a type or member, or by employing an unsafe-statement:

26• A declaration of a class, struct, interface, or delegate can include an unsafe modifier, in which case, the

27extent of that type-declaration is considered an unsafe context. [Note: If the type-declaration is partial,

28only that part is an unsafe context. end note]

29• A declaration of a field, method, property, event, indexer, operator, instance constructor, destructor, or

30static constructor can include an unsafe modifier, in which case, the entire textual extent of that

31member declaration is considered an unsafe context.

32• An unsafe-statement enables the use of an unsafe context within a block. The entire textual extent of the

33associated block is considered an unsafe context.

34The associated grammar extensions are shown below. For brevity, ellipses (...) are used to represent

35productions that appear in preceding clauses.

36class-modifier:

38unsafe

39struct-modifier:

379

C# LANGUAGE SPECIFICATION

3unsafe

4delegate-modifier:

6unsafe

7field-modifier:

9unsafe

10method-modifier:

12unsafe

13property-modifier:

15unsafe

16event-modifier:

18unsafe

19indexer-modifier:

21unsafe

22operator-modifier:

24unsafe

25constructor-modifier:

27unsafe

28destructor-declaration:

37static unsafeopt externopt

38embedded-statement:

41 unsafe-statement:

42unsafe block

43[Example: In the following code

44public unsafe struct Node

45{

48public Node* Right;

49}

380

Chapter 25 Unsafe code

1the unsafe modifier specified in the struct declaration causes the entire textual extent of the struct

2declaration to become an unsafe context. Thus, it is possible to declare the Left and Right fields to be of a

3pointer type. The example above could also be written

4public struct Node

5{

8public unsafe Node* Right;

9}

10Here, the unsafe modifiers in the field declarations cause those declarations to be considered unsafe

11contexts. end example]

12Other than establishing an unsafe context, thus permitting the use of pointer types, the unsafe modifier has

13no effect on a type or a member. [Example: In the following code

14public class A

15{

19}

20}

21public class B: A

22{

26}

27}

28the unsafe modifier on the F method in A simply causes the textual extent of F to become an unsafe

29context in which the unsafe features of the language can be used. In the override of F in B, there is no need

30to re-specify the unsafe modifier—unless, of course, the F method in B itself needs access to unsafe

31features.

32The situation is slightly different when a pointer type is part of the method’s signature

33public unsafe class A

34{

35public virtual void F(char* p) {…}

36}

37public class B: A

38{

39public unsafe override void F(char* p) {…}

40}

41Here, because F’s signature includes a pointer type, it can only be written in an unsafe context. However, the

42unsafe context can be introduced by either making the entire class unsafe, as is the case in A, or by including

43an unsafe modifier in the method declaration, as is the case in B. end example]

44When the unsafe modifier is used on a partial type declaration (§17.1.4), only that particular part is

45considered an unsafe context.

4625.2 Pointer types

47In an unsafe context, a type (§11) can be a pointer-type as well as a value-type, a reference-type, or a type-

48parameter.

49type:

381

Chapter 25 Unsafe code

1The void* type represents a pointer to an unknown type. Because the referent type is unknown, the

2indirection operator cannot be applied to a pointer of type void*, nor can any arithmetic be performed on

3such a pointer. However, a pointer of type void* can be cast to any other pointer type (and vice versa) and

4compared to values of other pointer types.

5Pointer types are a separate category of types. Unlike reference types and value types, pointer types do not

6inherit from object and no conversions exist between pointer types and object. In particular, boxing and

7unboxing (§11.3) are not supported for pointers. However, conversions are permitted between different

8pointer types and between pointer types and the integral types. This is described in §25.4.

9A pointer-type can be used as the type of a volatile field (§17.4.3).

10[Note: Although pointers can be passed as ref or out parameters, doing so can cause undefined behavior,

11since the pointer might well be set to point to a local variable which no longer exists when the called method

12returns, or the fixed object to which it used to point, is no longer fixed. For example:

13using System;

14class Test

15{

34}

35}

36end note]

37A method can return a value of some type, and that type can be a pointer. [Example: When given a pointer to

38a contiguous sequence of ints, that sequence's element count, and some other int value, the following

39method returns the address of that value in that sequence, if a match occurs; otherwise it returns null:

40unsafe static int* Find(int* pi, int size, int value) {

47return null;

48}

49end example]

50In an unsafe context, several constructs are available for operating on pointers:

51• The unary * operator can be used to perform pointer indirection (§25.5.1).

52• The -> operator can be used to access a member of a struct through a pointer (§25.5.2).

53• The [] operator can be used to index a pointer (§25.5.3).

54• The unary & operator can be used to obtain the address of a variable (§25.5.4).

383