From 5256cb67d95c17095778abf30fd6b67b39d1d578 Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Thu, 19 Dec 2019 16:16:15 +1100 Subject: [PATCH] Add hello-wuffs-c example Fixes #9 --- .gitignore | 1 + doc/wuffs-the-language.md | 6 ++ hello-wuffs-c/README.md | 161 +++++++++++++++++++++++++++++++++++++ hello-wuffs-c/main.c | 91 +++++++++++++++++++++ hello-wuffs-c/parse.wuffs | 49 +++++++++++ hello-wuffs-c/run.sh | 33 ++++++++ hello-wuffs-c/wuffs-base.c | 19 +++++ 7 files changed, 360 insertions(+) create mode 100644 hello-wuffs-c/README.md create mode 100644 hello-wuffs-c/main.c create mode 100644 hello-wuffs-c/parse.wuffs create mode 100755 hello-wuffs-c/run.sh create mode 100644 hello-wuffs-c/wuffs-base.c diff --git a/.gitignore b/.gitignore index bf9104c6..0ce92983 100644 --- a/.gitignore +++ b/.gitignore @@ -2,5 +2,6 @@ *.out *~ /gen +/hello-wuffs-c/parse.c Cargo.lock target diff --git a/doc/wuffs-the-language.md b/doc/wuffs-the-language.md index 306b10f6..cf226f42 100644 --- a/doc/wuffs-the-language.md +++ b/doc/wuffs-the-language.md @@ -85,3 +85,9 @@ not compile if overflow is possible. Some of these operators have alternative definition, these never overflow. The `as` operator, e.g. `x as T`, converts an expression `x` to the type `T`. + + +## Introductory Example + +A simple Wuffs the Language program, unrelated to Wuffs the Library, is +discussed in [/hello-wuffs-c](/hello-wuffs-c). diff --git a/hello-wuffs-c/README.md b/hello-wuffs-c/README.md new file mode 100644 index 00000000..8b19dce2 --- /dev/null +++ b/hello-wuffs-c/README.md @@ -0,0 +1,161 @@ +# Hello `wuffs-c` + +This directory contains a simple example of a C program using a Wuffs library. +It uses the `wuffs-c` command line tool, which transpiles from Wuffs code to +generate C code. + +Traditionally, the first program anyone writes in a given programming language +is something that prints "Hello world". This doesn't work for Wuffs, for two +reasons. One is that Wuffs doesn't have a string type per se. Two is that Wuffs +code doesn't even have the capability to write to files directly, such as to +`stdout`. Wuffs is a language for writing libraries, not complete programs, and +the less Wuffs can do, the less Wuffs can do that is surprising (such as upload +your files to the internet), even when processing untrusted input. + +Instead, we're going to run some Wuffs code that parses a string (like `"123"`) +and returns an integer (like `123`). It'll be similar to the C `atoi` function, +although our function will return unsigned instead of signed, as it's a simpler +problem. Our function will also take a pointer-length pair, not just a C style +pointer. Anyway, here's what the output should look like: + +``` +$ ./run.sh +0 +12 +56789 +4294967295 +0 +3197704724 +-------- +0 +12 +56789 +4294967295 +parse: demo: too large +0 +parse: demo: too large +0 +``` + +The [`run.sh`](/hello-wuffs-c/run.sh) script compiles and runs the +[`main.c`](/hello-wuffs-c/main.c) program twice, without and with Wuffs. On +each run, it parses 6 inputs. The first 4 are within the `uint32_t` range and +the last 2 are not. Here's an excerpt of `main.c`: + +``` +int main(int argc, char* argv) { + run("0"); + run("12"); + run("56789"); + run("4294967295"); // (1<<32) - 1, aka UINT32_MAX. + run("4294967296"); // (1<<32). + run("123456789012"); + return 0; +} +``` + +The first run (without Wuffs) uses a simple C implementation: + +``` +uint32_t parse(char* p, size_t n) { + uint32_t ret = 0; + for (size_t i = 0; (i < n) && p[i]; i++) { + ret = (10 * ret) + (p[i] - '0'); + } + return ret; +} +``` + +This works for the first 4 inputs, but silently overflows for the last 2. A +subtle point is that, by default, the C compiler accepted this code without any +indication that integer overflow could occur, yet integer overflow can lead to +[serious bugs](https://en.wikipedia.org/wiki/Stagefright_%28bug%29). + +Some C compilers, and some compilers for other languages, can optionally insert +run-time checks for integer overflow, but these are typically disabled by +default because of the performance impact. Having these checks enabled for +developer builds are better than nothing, but it still isn't a complete +solution. We don't ship developer builds to our users, and while computer +programmers are better than the average person at e.g. spotting phising +attempts, that also means that they can be less likely than the average person +to 'test' their developer builds on the malicious input that users encounter. + +Anyway, in Wuffs, integer overflow is a mandatory concern. Addressing that +concern takes a little more code, this time in Wuffs: + +``` +pub func parser.parse?(src: base.io_reader) { + var c : base.u8 + while true { + c = args.src.read_u8?() + if c == 0 { + return ok + } + if (c < 0x30) or (0x39 < c) { // '0' and '9' are ASCII 0x30 and 0x39. + return "#not a digit" + } + // Rebase from ASCII (0x30 ..= 0x39) to the value (0 ..= 9). + c -= 0x30 + + if this.val < 429496729 { + this.val = (10 * this.val) + (c as base.u32) + continue + } else if (this.val > 429496729) or (c > 5) { + return "#too large" + } + // Uncomment this assertion to see what facts are known here. + // assert false + this.val = (10 * this.val) + (c as base.u32) + } +} +``` + +Obviously, we could have written the same careful algorithm in C. The point is +that, unlike C, Wuffs doesn't let you forget to consider integer (or buffer) +overflows. This can certainly be annoying in general, but reassuring whenever +the code has to run in security-concious contexts. + +Play with the [parse.wuffs](/hello-wuffs-c/parse.wuffs) code and see what sort +of compiler errors you get: + +```diff +diff --git a/hello-wuffs-c/parse.wuffs b/hello-wuffs-c/parse.wuffs +index cb207eec..c38dcf88 100644 +--- a/hello-wuffs-c/parse.wuffs ++++ b/hello-wuffs-c/parse.wuffs +@@ -35,7 +35,7 @@ pub func parser.parse?(src: base.io_reader) { + if this.val < 429496729 { + this.val = (10 * this.val) + (c as base.u32) + continue +- } else if (this.val > 429496729) or (c > 5) { ++ } else if (this.val > 429496729) { + return "#too large" + } + // Uncomment this assertion to see what facts are known here. +``` + +``` +$ ./run.sh +check: expression "(10 * this.val) + (c as base.u32)" bounds [4294967290 ..= 4294967299] is not within bounds [0 ..= 4294967295] at stdin:43. Facts: + c <> -48 + c >= 0 + c <= 9 + this.val >= 429496729 + this.val <= 429496729 +``` + +Note that the `parser.parse` method is a [coroutine](/doc/note/coroutines.md) +and therefore doesn't return the value directly. Instead, the pattern is that +the `parse` method updates the state and the `value` method returns the state. +For more realistic problem domains, the output often isn't just a single +`uint32_t`, and the pattern for e.g. image decoding in Wuffs is that the +`decode` method takes the destination buffer as an additional argument. + +That's the end of this "Hello world"-ish introduction. After that, you can read +more documentation about both [Wuffs the Language](/doc/wuffs-the-language.md) +and [Wuffs the Library](/doc/wuffs-the-library.md). + +Finally, there are admittedly a couple of TODOs in this directory, concerning +some rough edges in what should be a simple example. Version 0.2 (December +2019) has prioritized users of Wuffs the Library over users of Wuffs the +Language. A future version should fix that imbalance. diff --git a/hello-wuffs-c/main.c b/hello-wuffs-c/main.c new file mode 100644 index 00000000..b6cbaea6 --- /dev/null +++ b/hello-wuffs-c/main.c @@ -0,0 +1,91 @@ +// Copyright 2019 The Wuffs Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// ---------------- + +#include +#include +#include +#include + +#ifndef USE_WUFFS +uint32_t parse(char* p, size_t n) { + uint32_t ret = 0; + for (size_t i = 0; (i < n) && p[i]; i++) { + ret = (10 * ret) + (p[i] - '0'); + } + return ret; +} +#else // #ifndef USE_WUFFS + +// TODO: this 'rough edge' shouldn't be necessary. See +// https://github.com/google/wuffs/issues/24 +#define WUFFS_CONFIG__MODULE__BASE + +#define WUFFS_IMPLEMENTATION +#include "./parse.c" + +uint32_t parse(char* p, size_t n) { + wuffs_base__status status; + wuffs_demo__parser* parser = + (wuffs_demo__parser*)(malloc(sizeof__wuffs_demo__parser())); + if (!parser) { + printf("malloc failed\n"); + return 0; + } + + status = wuffs_demo__parser__initialize(parser, sizeof__wuffs_demo__parser(), + WUFFS_VERSION, 0); + if (!wuffs_base__status__is_ok(status)) { + printf("initialize: %s\n", wuffs_base__status__message(status)); + free(parser); + return 0; + } + + wuffs_base__io_buffer iobuf; + iobuf.data.ptr = (uint8_t*)p; + iobuf.data.len = n; + iobuf.meta.wi = n; + iobuf.meta.ri = 0; + iobuf.meta.pos = 0; + iobuf.meta.closed = true; + + status = wuffs_demo__parser__parse(parser, &iobuf); + if (!wuffs_base__status__is_ok(status)) { + printf("parse: %s\n", wuffs_base__status__message(status)); + free(parser); + return 0; + } + + uint32_t ret = wuffs_demo__parser__value(parser); + free(parser); + return ret; +} +#endif // #ifndef USE_WUFFS + +void run(char* p) { + size_t n = strlen(p) + 1; // +1 for the trailing NUL that ends a C string. + uint32_t i = parse(p, n); + printf("%" PRIu32 "\n", i); +} + +int main(int argc, char** argv) { + run("0"); + run("12"); + run("56789"); + run("4294967295"); // (1<<32) - 1, aka UINT32_MAX. + run("4294967296"); // (1<<32). + run("123456789012"); + return 0; +} diff --git a/hello-wuffs-c/parse.wuffs b/hello-wuffs-c/parse.wuffs new file mode 100644 index 00000000..cb207eec --- /dev/null +++ b/hello-wuffs-c/parse.wuffs @@ -0,0 +1,49 @@ +// Copyright 2019 The Wuffs Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +pri status "#not a digit" +pri status "#too large" + +pub struct parser?( + val : base.u32, +) + +pub func parser.parse?(src: base.io_reader) { + var c : base.u8 + while true { + c = args.src.read_u8?() + if c == 0 { + return ok + } + if (c < 0x30) or (0x39 < c) { // '0' and '9' are ASCII 0x30 and 0x39. + return "#not a digit" + } + // Rebase from ASCII (0x30 ..= 0x39) to the value (0 ..= 9). + c -= 0x30 + + if this.val < 429496729 { + this.val = (10 * this.val) + (c as base.u32) + continue + } else if (this.val > 429496729) or (c > 5) { + return "#too large" + } + // Uncomment this assertion to see what facts are known here. + // assert false + this.val = (10 * this.val) + (c as base.u32) + } +} + +pub func parser.value() base.u32 { + return this.val +} diff --git a/hello-wuffs-c/run.sh b/hello-wuffs-c/run.sh new file mode 100755 index 00000000..ac3f9a6f --- /dev/null +++ b/hello-wuffs-c/run.sh @@ -0,0 +1,33 @@ +#!/bin/bash -eu +# Copyright 2019 The Wuffs Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# ---------------- + +CC=${CC:-gcc} + +# You may need to run +# go get github.com/google/wuffs/cmd/wuffs-c +# beforehand, to install the wuffs-c compiler. +wuffs-c gen -package_name demo < parse.wuffs > parse.c + +$CC main.c +./a.out + +echo -------- + +$CC main.c -DUSE_WUFFS +./a.out + +rm a.out parse.c diff --git a/hello-wuffs-c/wuffs-base.c b/hello-wuffs-c/wuffs-base.c new file mode 100644 index 00000000..95a34718 --- /dev/null +++ b/hello-wuffs-c/wuffs-base.c @@ -0,0 +1,19 @@ +// Copyright 2019 The Wuffs Authors. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// https://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// ---------------- + +// TODO: this 'rough edge' shouldn't be necessary. See +// https://github.com/google/wuffs/issues/24 +#include "../release/c/wuffs-unsupported-snapshot.c"