GCC Middle and Back End API Reference
string-scan.h
Go to the documentation of this file.
1/* Support for scanning buffers for a NUL terminator (for C-style strings).
2 Copyright (C) 2026 Free Software Foundation, Inc.
3 Contributed by David Malcolm <dmalcolm@redhat.com>.
4
5This file is part of GCC.
6
7GCC is free software; you can redistribute it and/or modify it
8under the terms of the GNU General Public License as published by
9the Free Software Foundation; either version 3, or (at your option)
10any later version.
11
12GCC is distributed in the hope that it will be useful, but
13WITHOUT ANY WARRANTY; without even the implied warranty of
14MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15General Public License for more details.
16
17You should have received a copy of the GNU General Public License
18along with GCC; see the file COPYING3. If not see
19<http://www.gnu.org/licenses/>. */
20
21#ifndef GCC_ANALYZER_STRING_SCAN_H
22#define GCC_ANALYZER_STRING_SCAN_H
23
25
26namespace ana {
27
28/* A class representing the result of a scan through a bit_vector,
29 bit_contents, or constant at some start offset looking for the first of:
30 - NUL terminator (if any), or
31 - an access that will trigger a diagnostic (if any), e.g. uninitialized, or
32 - exhausting the domain of the input
33
34 Records what happened, and the offset at which it happened. The
35 offset is relative to the start of the buffer, rather than the given
36 start offset, i.e. they are both in the same "coordinate system".
37 For exhausted data, this will be the index of one past the last
38 valid element, i.e. the size of the bit_vector/constant. */
39
41{
43
44 /* A enum to discriminate the different kinds of result. */
45 enum class state
46 {
47 /* Found a NUL terminator.
48 Result offset is that of the NUL (which could be that
49 of the start_byte_offset).
50 . +-----+-----+-----+-----+-----+-----+
51 . | 'a' | 'b' | 'c' | 'd' | NUL | NUL |
52 . +-----+-----+-----+-----+-----+-----+
53 . ^ ^
54 . | result offset
55 . start_byte_offset. */
57
58 /* Found a poisoned byte (e.g. uninitialized)
59 Result offset is that of the problematic byte.
60 . +-----+-----+-----+-----+------+-----+
61 . | 'a' | 'b' | 'c' | 'd' |uninit| NUL |
62 . +-----+-----+-----+-----+------+-----+
63 . ^ ^
64 . | result offset
65 . start_byte_offset. */
67
68 /* Didn't find any terminators or problems.
69 Result offset is one past the end of the domain of the bit_vector
70 or constant, which is its size in bytes.
71 . +-----+-----+-----+-----+-----+-----+......+
72 . | | | | | | | ..
73 . +-0---+-----+-----+-----+-----+-----+.size.+
74 . ^ ^
75 . start_byte_offset result offset. */
77
78 /* This object can't be scanned for some reason.
79 The result offset is where the problem occurred
80 (often the start byte offset). */
82 };
83
85 enum state state)
86 : m_byte_offset (byte_offset),
87 m_state (state),
89 {
90 }
91
93 enum poison_kind poison_kind_)
94 : m_byte_offset (byte_offset),
96 m_poison_kind (poison_kind_)
97 {
98 }
99
100 static string_scan
102 {
103 return string_scan (byte_offset, state::found_nul);
104 }
105 static string_scan
107 enum poison_kind poison_kind_)
108 {
109 return string_scan (byte_offset, poison_kind_);
110 }
111 static string_scan
113 {
114 // byte offset == offset of 1 past the end of the buffer == buffer size
115 return string_scan (byte_offset, state::beyond_domain);
116 }
117 static string_scan
119 {
120 return string_scan (byte_offset, state::cannot_scan);
121 }
122
123 bool
124 operator== (const string_scan &other) const
125 {
126 return (m_byte_offset == other.m_byte_offset
127 && m_state == other.m_state);
128 }
129
130 void dump_to_pp (pretty_printer *pp) const;
131 void dump () const;
132
133 static const char *
135
139};
140
141} // namespace ana
142
143#endif /* GCC_ANALYZER_STRING_SCAN_H */
Definition pretty-print.h:241
Definition access-diagram.h:30
poison_kind
Definition common.h:520
@ other
Definition common.h:535
integer_with_unit< units::byte > concrete_byte_offset
Definition integer-with-unit.h:331
Definition string-scan.h:41
enum poison_kind m_poison_kind
Definition string-scan.h:138
string_scan(byte_offset_type byte_offset, enum state state)
Definition string-scan.h:84
static string_scan found_nul(byte_offset_type byte_offset)
Definition string-scan.h:101
static string_scan beyond_domain(byte_offset_type byte_offset)
Definition string-scan.h:112
string_scan(byte_offset_type byte_offset, enum poison_kind poison_kind_)
Definition string-scan.h:92
void dump() const
void dump_to_pp(pretty_printer *pp) const
static const char * state_to_string(enum state s)
concrete_byte_offset byte_offset_type
Definition string-scan.h:42
byte_offset_type m_byte_offset
Definition string-scan.h:136
static string_scan cannot_scan(byte_offset_type byte_offset)
Definition string-scan.h:118
state
Definition string-scan.h:46
@ beyond_domain
Definition string-scan.h:76
@ found_nul
Definition string-scan.h:56
@ cannot_scan
Definition string-scan.h:81
static string_scan found_poison(byte_offset_type byte_offset, enum poison_kind poison_kind_)
Definition string-scan.h:106
bool operator==(const string_scan &other) const
Definition string-scan.h:124
enum state m_state
Definition string-scan.h:137