add more details

5 files changed, 43 insertions, 4 deletions

diff --git a/_build.yml b/_build.yml
new file mode 100644
index 0000000..3276c5f
--- /dev/null
+++ b/_build.yml
@@ -0,0 +1,13 @@
+image: debian/stable

+packages:

+    - pandoc

+    - wkhtmltopdf

+    - poppler-utils

+sources:

+    - https://git.sr.ht/~boringcactus/crowbar-spec

+tasks:

+    - page-count: |

+        cd crowbar-spec

+        pandoc -s -o ../spec.pdf -t html *.md

+        cd ..

+        pdfinfo spec.pdf | grep Pages

diff --git a/index.md b/index.md
index 55d1646..2d19c0a 100644
--- a/index.md
+++ b/index.md
@@ -26,7 +26,6 @@ Some of the footguns and complexity in C come from misfeatures that can simply n
 -   Chaining relational/equality operators (e.g. `3 < x == 2`)

 -   Mixed chains of bitwise or logical operators (e.g. `2 & x && 4 ^ y`)

 -   The comma operator `,`

--   Strings that aren't UTF-8

 

 ### Explicit Beats Implicit

 

@@ -53,14 +52,17 @@ Some of the footguns and complexity in C come from misfeatures that can simply n
 

 Some C features are footguns by default, so Crowbar ensures that they are only used correctly.

 

--   Unions blah blah blah

+-   Unions are not robust by default.

+    Crowbar only supports unions when they are [tagged unions](tagged-unions.md).

 

 C's syntax isn't perfect, but it's usually pretty good.

 However, sometimes it just sucks, and in those cases Crowbar makes changes.

 

--   Complicated types (function pointers, pointer-to-`const` vs `const`-pointer, etc)

+-   C's variable declaration syntax is far from intuitive in nontrivial cases (function pointers, pointer-to-`const` vs `const`-pointer, etc).

+    Crowbar uses [simplified type syntax](types.md) to keep types and variable names distinct.

 -   `_Bool` is just `bool`, `_Complex` is just `complex` (why drag the preprocessor into it?)

 -   Adding a `_` to numeric literals as a separator

+-   All string literals, char literals, etc are UTF-8

 

 # Additions

 

diff --git a/safety.md b/safety.md
index d353227..6550492 100644
--- a/safety.md
+++ b/safety.md
@@ -4,7 +4,29 @@ Each item in Wikipedia's [list of types of memory errors](https://en.wikipedia.o
 

 ## Buffer overflow

 

-bounds checking based on uhhhh something

+Crowbar addresses buffer overflow with bounds checking.

+In C, the type `char *` can point to a single character, a null-terminated string of unknown length, a buffer of fixed size, or nothing at all.

+In Crowbar, the type `char *` can only point to either a single character or nothing at all.

+If a buffer is declared as `char[50] name;` then it has type `char[50]`, and can be implicitly converted to `(char[50])*`, a pointer-to-50-chars.

+If memory is dynamically allocated, it works as follows:

+

+```crowbar

+void process(size_t bufferSize, char[bufferSize] buffer) {

+    // do some work with buffer, given that we know its size

+}

+

+int main(int argc, (char[1024?])[argc] argv) {

+    size_t bufferSize = getBufferSize();

+    (char[bufferSize])* buffer = malloc(bufferSize);

+    process(bufferSize, buffer);

+    free(buffer);

+}

+```

+

+Note that `malloc` as part of the Crowbar standard library has signature `(char[size])* malloc(size_t size);` and so no cast is needed above.

+Note as well that the type of `argv` is complicated.

+This is because the elements of `argv` have unconstrained size.

+TODO figure out if that's the right way to handle that

 

 ## Buffer over-read

 

diff --git a/tagged-unions.md b/tagged-unions.md
new file mode 100644
index 0000000..1ea1912
--- /dev/null
+++ b/tagged-unions.md
@@ -0,0 +1 @@
+TODO

diff --git a/types.md b/types.md
new file mode 100644
index 0000000..1ea1912
--- /dev/null
+++ b/types.md
@@ -0,0 +1 @@
+TODO