retroforth/doc/html/chapters/techniques/sockets.html
crc 5c52887aa8 fix #101: epub: chapter names are not rendered
FossilOrigin-Name: 7dd2b1bd7506c2c488b70620ba9d889f3a9a3d58f99b4dba1d6923e0ac0edb8d
2024-09-06 10:39:30 +00:00

114 lines
4.5 KiB
HTML

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<title>doc/book/techniques/sockets</title>
<style type="text/css">
* { color: #000; background: #fff; max-width: 700px; }
tt, pre { background: #dedede; color: #111; font-family: monospace;
white-space: pre; display: block; width: 100%; }
.indentedcode { margin-left: 2em; margin-right: 2em; }
.codeblock {
background: #dedede; color: #111; font-family: monospace;
box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
padding: 7px;
display: block;
}
.indentedlist { margin-left: 2em; color: #000; }
span { white-space: pre; }
.text { color: #000; white-space: pre; background: #dedede; }
.colon { color: #000; background: #dedede; }
.note { color: #000; background: #dedede; }
.str { color: #000; text-decoration: underline; background: #dedede; }
.num { color: #000; background: #dedede; font-weight: bold; font-style: italic; }
.fnum { color: #000; font-weight: bold; background: #dedede; }
.ptr { color: #000; font-weight: bold; background: #dedede; }
.fetch { color: #000; font-style: italic; background: #dedede; }
.store { color: #000; font-style: italic; background: #dedede; }
.char { color: #000; background: #dedede; }
.inst { color: #000; background: #dedede; }
.defer { color: #000; background: #dedede; }
.imm { color: #000; font-weight: bold; background: #dedede; }
.prim { color: #000; font-weight: bolder; background: #dedede; }
.tt { white-space: pre; font-family: monospace; background: #dedede; }
.h1, .h2, .h3, .h4 { white-space: normal; }
.h1 { font-size: 125%; }
.h2 { font-size: 120%; }
.h3 { font-size: 115%; }
.h4 { font-size: 110%; }
.hr { display: block; height: 2px; background: #000000; }
</style>
</head><body>
<p><span class="h1">Sockets</span>
<br/><br/>
On Unix hosts, RETRO provides an optional set of words for using
network sockets.
<br/><br/>
<span class="h2">Create a Socket</span>
<br/><br/>
To create a new socket, just run:
<br/><br/>
<tt class='indentedcode'>socket:create</tt>
<br/><br/>
This will return a socket handle.
<br/><br/>
<span class="h2">Bind To A Port</span>
<br/><br/>
To bind to a port, pass the port number and socket handle
to <span class="tt">socket:bind</span>. The port should be a string. This will return
0 if successful, -1 if not successful, and an error code.
<br/><br/>
<tt class='indentedcode'>'9998&nbsp;@Sock&nbsp;socket:bind</tt>
<br/><br/>
<span class="h2">Configure To Allow Incoming Connections</span>
<br/><br/>
To prepare a socket for incoming connections use socket:listen. This
will take a backlog count and a socket handle. It returns a flag
(0 success, -1 failed) and an error code.
<br/><br/>
<tt class='indentedcode'>#3&nbsp;@Sock&nbsp;socket:listen</tt>
<br/><br/>
<span class="h2">Accept Connections</span>
<br/><br/>
To accept connections pass the socket handle to <span class="tt">socket:accept</span>.
This returns a new socket for the connection and an error code.
<br/><br/>
<tt class='indentedcode'>@Sock&nbsp;socket:accept</tt>
<br/><br/>
<span class="h2">Make A Connection</span>
<br/><br/>
To connect to a server using the socket:
<br/><br/>
<tt class='indentedcode'>'forth.works&nbsp;'70&nbsp;socket:configure</tt>
<tt class='indentedcode'>@Sock&nbsp;socket:connect</tt>
<br/><br/>
<span class="tt">socket:connect</span> will return a status code and an error code.
<br/><br/>
<span class="h2">Writing To A Socket</span>
<br/><br/>
To write a string to a socket, use <span class="tt">socket:send</span>. This will
take a string and a socket handle and will return the number
of bytes sent and an error code.
<br/><br/>
<tt class='indentedcode'>'test&nbsp;@Sock&nbsp;socket:send</tt>
<br/><br/>
<span class="h2">Reading From A Socket</span>
<br/><br/>
To read data from a socket pass an address, a maximum number of
bytes, and the socket handle to <span class="tt">socket:recv</span>. This will return
the number of bytes received and an error code. The bytes will
be stored in memory starting at the specified address.
<br/><br/>
<tt class='indentedcode'>here&nbsp;#1024&nbsp;@Sock&nbsp;socket:recv</tt>
<br/><br/>
<span class="h2">Close a Socket</span>
<br/><br/>
To close a socket, pass the socket handle to <span class="tt">socket:close</span>.
<br/><br/>
<tt class='indentedcode'>@Socket&nbsp;socket:close</tt>
</p>
</body></html>