mirror of
https://github.com/ddidderr/wuffs.git
synced 2026-11-19 00:38:14 +01:00
1 parent
aaa30fc5a6
commit
5256cb67d9
7 files changed
+360
No files matched your search
@@ -2,5 +2,6 @@
|
||||
*.out
|
||||
*~
|
||||
/gen
|
||||
/hello-wuffs-c/parse.c
|
||||
Cargo.lock
|
||||
target
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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 <inttypes.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
|
||||
#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;
|
||||
}
|
||||
@@ -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
|
||||
}
|
||||
Executable
+33
@@ -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
|
||||
@@ -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"
|
||||
Reference in new issue
Block a user