summaryrefslogtreecommitdiff
path: root/doc/api/libstd/networking.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api/libstd/networking.txt')
-rw-r--r--doc/api/libstd/networking.txt181
1 files changed, 0 insertions, 181 deletions
diff --git a/doc/api/libstd/networking.txt b/doc/api/libstd/networking.txt
deleted file mode 100644
index 0229573..0000000
--- a/doc/api/libstd/networking.txt
+++ /dev/null
@@ -1,181 +0,0 @@
-{
- title: Networking
- description: libstd: Networking
-}
-Networking
-----------
-
- pkg std =
- type netaddr = union
- `Ipv4 byte[4]
- `Ipv6 byte[16]
- ;;
-
-
- /* network connections */
- const dial : (dialstr : byte[:] -> result(fd, byte[:]))
- const announce : (ds : byte[:] -> result(fd, byte[:]))
- const listen : (sock : fd -> result(fd, byte[:]))
- const accept : (lfd : fd -> result(fd, byte[:]))
-
- /* ip parsing */
- const ipparse : (ip : byte[:] -> option(netaddr))
- const ip4parse : (ip : byte[:] -> option(netaddr))
- const ip6parse : (ip : byte[:] -> option(netaddr))
-
- generic hosttonet : (v : @a -> @a)
- generic nettohost : (v : @a -> @a)
- ;;
-
-Summary
--------
-
-This group of functions contains the basic, portable networking functionality
-provided by libstd. There are other packages shipped which provide access
-to the underlying functionality used to implement this code, and which may
-provide more control.
-
-The bulk of the functionality is fairly low level. Most of the client side
-networking should be done using nothing more than `dial` and `announce`
-
-Dial describes the endpoint to connect to in the form `proto!host!service`.
-`proto` can be any supported protocol. The host specified can be an IP
-address, hostname, or path to a local socket. The service ismay be either a
-named service, or a protocol specific port. If the port is not a component of
-the address (eg, Unix domain sockets) then it should be ommitted.
-
-On plan 9, the full dial(2) dial string syntax is suported.
-
-Data Types
-----------
-
-This contains the infomation that we extract by resolving a host.
-
- type ipaddr = union
- `Ipv4 byte[4]
- `Ipv6 byte[16]
- ;;
-
-This contains an IP address. Either V4 or V6 is supported.
-
-Connections
-----------
-
- const dial : (dialstr : byte[:] -> result(fd, byte[:]))
-
-Dial connects to a dial string as described in the summary, returning either a
-file descriptor on success, or an error description on failure. The FD
-returned is a connection to the server.
-
- const announce : (ds : byte[:] -> result(fd, byte[:]))
-
-Announce sets up a file descriptor which is ready to listen for connections,
-and binds it to an address. Wildcards can be specified with '*' within the
-dial string.
-
- const listen : (sock : fd -> result(fd, byte[:]))
-
-Listen specifies that the socket created with `announce` is willing to accept
-connections.
-
- const accept : (lfd : fd -> result(fd, byte[:]))
-
-Accept takes the returned file descriptor from listen, and returns a file
-descriptor that is prepared for reading and writing.
-
-IP Parsing
-----------
-
- const ipparse : (ip : byte[:] -> option(netaddr))
-
-Ipparse will parse an IP address. This will recognize either V4 or V6
-addresses, and `\`Some \`Ipv4 bits or `\`Some \`Ipv6 bits` as appropriate, or
-`\`None` if the address can't be parsed.
-
- const ip4parse : (ip : byte[:] -> option(netaddr))
-
-Parses an Ipv4 address from the string `ip`. The syntax expected is dotted
-quad notation. Returns `\` Some \`Ipv4 bits` if the address parses successfully, or
-`\`None` if parsing fails.
-
- const ip6parse : (ip : byte[:] -> option(netaddr))
-
-Parses an Ipv6 address from the string `ip`. Returns `\` Some \`Ipv4 bits` if
-the address parses successfully, or `\`None` if parsing fails. Zones are
-currently not supported. This is a bug.
-
-
-Endian flipping
---------------
-
- generic hosttonet : (v : @a -> @a)
- generic nettohost : (v : @a -> @a)
-
-
-Flips the bits in an integer to match the expected. These functions should be
-avoided in favor of explicit packing functions.
-
-Examples
---------
-
-Some simple examples of how to use the Myrddin networking API
-
-#### Echo Server
-
- use std
-
- const Dialstr = "tcp!*!1234"
- const main = {
- var lfd, afd
- var buf : byte[1024]
-
- match std.announce(Dialstr)
- | `std.Ok f: lfd = f
- | `std.Fail e: std.fatal("unable to announce on {}: {}\n", Dialstr, e)
- ;;
-
- match std.listen(lfd)
- | `std.Ok f: afd = f
- | `std.Fail e: std.fatal("unable to listen on {}: {}\n", Dialstr, e)
- ;;
-
- while true
- match std.accept(afd)
- | `std.Ok fd:
- match std.read(fd, buf[:])
- | `std.Ok n:
- std.writeall(fd, buf[:n])
- | `std.Fail e:
- std.put("lost conection while reading: {}\n", e)
- ;;
- std.close(fd)
- | `std.Fail e:
- std.fatal("unable to accept connection on {}: {}\n", Dialstr, e)
- ;;
- ;;
- }
-
-
-#### Echo Client
-
- use std
-
- const Dialstr = "tcp!localhost!1234"
- const main = {args : byte[:][:]
- var req, resp
-
- match std.dial(Dialstr)
- | `std.Ok fd:
- req = std.strjoin(args[1:], " ")
- std.writeall(fd, req)
- resp = std.try(std.fslurp(fd))
- std.put("{}\n", resp)
- | `std.Fail e:
- std.fatal("unable to dial {}: {}\n", Dialstr, e)
- ;;
- }
-
-Bugs
-----
-The errors returned are strings, when they should be unions with default
-formatting functions.