From 8a5a4669f718d76a1315d9ae40a824181a320f1b Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Fri, 2 Apr 2021 14:45:30 -0400 Subject: [PATCH] WIP --- docs/api/srfi/106.md | 225 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) diff --git a/docs/api/srfi/106.md b/docs/api/srfi/106.md index 63cdf7f2..dc25bf94 100644 --- a/docs/api/srfi/106.md +++ b/docs/api/srfi/106.md @@ -56,26 +56,190 @@ See the [SRFI document](http://srfi.schemers.org/srfi-106/srfi-106.html) for mor # make-client-socket + (make-client-socket node service [ai-family [ai-socktype [ai-flags [ai-protocol]]]]) -> socket + +Returns a client socket connected to an Internet address. +The Internet address is identified by node and service. node and service must be string. +Example value of node: `"localhost" "127.0.0.1"` +Example value of service: `"http" "80"` +The optional parameter may specify the created socket's behaviour. +If the optional argument(s) is omitted, then following flags should be used as default: + + ai-family + *af-inet* + ai-socktype + *sock-stream* + ai-flags + (socket-merge-flags *ai-v4mapped* *ai-addrconfig*) + ai-protocol + *ipproto-ip* + +The created socket may not be closed automatically so it is users' responsibility to close it explicitly. + # make-server-socket + (make-server-socket service [ai-family [ai-socktype [ai-protocol]]]) -> socket + +Returns a server socket waiting for connection. +The description of node argument is the same as make-client-socket. +The optional parameter may specify the created socket's behaviour. + +If the optional argument(s) is omitted, then following flags should be used as default. + + ai-family + *af-inet* + ai-socktype + *sock-stream* + ai-protocol + *ipproto-ip* + +The created socket may not be closed automatically so it is users' responsibility to close it explicitly. + # socket? +socket? object -> boolean +Returns #t if given object is socket object. Otherwise #f. + # socket-accept + (socket-accept socket) -> socket + +Wait for an incoming connection request, and returns a fresh connected client socket. + # socket-send + (socket-send socket bv [flags]) -> size + +Sends a binary data block to a socket and returns the sent data size. +`flags` may specify the procedure's behaviour. +If the `flags` is omitted, the default value must be the result of following form: + + (message-type none) + # socket-recv + (socket-recv socket size [flags]) -> bv + +Receives a binary data block from a socket. If zero length bytevector is returned, it means the peer connection is closed. +`flags` may specify the procedure's behaviour. +If the `flags` is omitted, the default value must be the result of following form; + + (message-type none) + # socket-shutdown + (socket-shutdown socket how) -> (unspecified) + +Shutdowns a socket. +`how` must be one of the following constants: + + *shut-rd* + *shut-wr* + *shut-rdwr* + # socket-close + (socket-close socket) -> (unspecified) + +Closes a socket. +The procedure does not shutdown the given socket. To shutdown a socket, socket-shutdown should be called explicitly. + # socket-input-port + (socket-input-port socket) -> binary-input-port + +Returns a fresh binary input port associated with a socket, respectively. +The port should not close underlying socket when it's closing. + # socket-output-port + (socket-output-port socket) -> binary-output-port + +Returns a fresh binary output port associated with a socket, respectively. +The port should not close underlying socket when it's closing. + # call-with-socket + (call-with-socket socket proc) -> object + +Calls a given procedure with a given socket as an argument. + +If given `proc` returns then it returns the result of `proc` and socket will be automatically closed. If `proc` doesn't return then given socket won't be closed automatically. It's analogy of `call-with-port`. + + + + + + +Following, address-family, address-info, socket-domain, ip-protocol, message-type and shutdown-method must be implemented as macros. +address-family name -> address-family +Returns proper address family from given name. +Implementation must support at least following names and must have the described behaviour. +inet +Returns *af-inet* +inet6 +Returns *af-inet6* +unspec +Returns *af-unspec* +Implementation may support more names such as unix or local or other names. +address-info names ... -> address-info +Returns merged address info flags from given names. +Implementation must support at least following names and must have the described behaviour. +canoname +Returns *ai-canonname* +numerichost +Returns *ai-numerichost* +v4mapped +Returns *ai-v4mapped* +all +Returns *ai-all* +addrconfig +Returns *ai-addrconfig* +Implementation may support more names. +socket-domain name -> socket-domain +Returns socket domain flags from given name. +Implementation must support at least following names and must have the described behaviour. +stream +Returns *sock-stream* +datagram +Returns *sock-dgram* +Implementation may support more names. +ip-protocol name -> ip-protocol +Returns ip-protocol flag from given name. +Implementation must support at least following names and must have the described behaviour. +ip +Returns *ipproto-ip* +tcp +Returns *ipproto-tcp* +udp +Returns *ipproto-udp* +Implementation may support more names. +message-type names ... -> message-type +Returns message type flag from given name. +The flag can be used both socket-recv and socket-send. +Implementation must support at least following names and must have the described behaviour. +none +Returns no flag. +peek +Returns *msg-peek* +oob +Returns *msg-oob* +wait-all +Returns *msg-waitall* +Implementation may support more names. +shutdown-method names ... -> shutdown-method +Returns shutdown method flags from given names. +Implementation must support at least following names and must have the described behaviour. +read +Returns *shut-rd* +write +Returns *shut-wr* +If shutdown-method is given both read and write, then it must return *shut-rdwr* +socket-merge-flags flags ... -> new-flags +Merges given flags and returns a new flag. +socket-purge-flags base-flag flags ... -> new-flags +Removes flags from base-flag if exists and returns a new flag. + # address-family # address-info @@ -92,41 +256,102 @@ See the [SRFI document](http://srfi.schemers.org/srfi-106/srfi-106.html) for mor # socket-purge-flags + + + + + + + # \*af-unspec\* +This must behave the same as POSIX's `AF_UNSPEC`. + # \*af-inet\* +Internet domain sockets for use with IPv4 addresses. +This must behave the same as POSIX's `AF_INET`. + # \*af-inet6\* +Internet domain sockets for use with IPv6 addresses. +This must behave the same as POSIX's `AF_INET6`. + # \*sock-stream\* +Byte-stream socket. +This must behave the same as POSIX's `SOCK_STREAM`. + # \*sock-dgram\* +Datagram socket. +This must behave the same as POSIX's `SOCK_DGRAM`. + # \*ai-canonname\* +This must behave the same as POSIX's `AI_CANONNAME`. + # \*ai-numerichost\* +This must behave the same as POSIX's `AI_NUMERICHOST`. + # \*ai-v4mapped\* +This must behave the same as POSIX's `AI_V4MAPPED`. + # \*ai-all\* +This must behave the same as POSIX's `AI_ALL`. + # \*ai-addrconfig\* +This must behave the same as POSIX's `AI_ADDRCONFIG`. + # \*ipproto-ip\* +Internet protocol. +This must behave the same as POSIX's `IPPROTO_IP`. + # \*ipproto-tcp\* +Transmission control protocol. +This must behave the same as POSIX's `IPPROTO_TCP`. + # \*ipproto-udp\* +User datagram protocol. +This must behave the same as POSIX's `IPPROTO_UDP`. + # \*msg-peek\* +For socket-recv. +Peeks at an incoming message. The data is treated as unread and the next socket-recv shall still return this data. +This must behave the same as `POSIX's MSG_PEEK`. + # \*msg-oob\* +For both `socket-recv` and `socket-send`. +Requests/sends out-of-band data. +This must behave the same as POSIX's `MSG_OOB`. + # \*msg-waitall\* +For socket-recv. +On sockets created with `*sock-stream*` flag, this requests the procedure block until the full amount of data ban be returned. +This must behave the same as POSIX's `MSG_WAITALL`. + # \*shut-rd\* +Disables further receive operation. +This must behave the same as POSIX's `SHUT_RD`. + # \*shut-wr\* +Disables further send operations. +This must behave the same as POSIX's `SHUT_WR`. + # \*shut-rdwr\* +Disables further send and receive operations. +This must behave the same as POSIX's `SHUT_RDWR`. +