aboutsummaryrefslogtreecommitdiff
path: root/docs/serial.html
diff options
context:
space:
mode:
authorThijs Schreijer <thijs@thijsschreijer.nl>2026-09-01 10:00:21 +0200
committerThijs Schreijer <thijs@thijsschreijer.nl>2026-09-01 10:48:40 +0200
commit70f7800986812ad0d1a5dd6f280f66fd2bf1dd12 (patch)
tree36051874b3ce036307d4bb69b3c4058458b6255d /docs/serial.html
parentfa9b35a0cf11bc856cbd8bffbef5ad6fb3e62a93 (diff)
downloadluasocket-docs/pre-release-audit.tar.gz
luasocket-docs/pre-release-audit.tar.bz2
luasocket-docs/pre-release-audit.zip
docs: document socket.unix and socket.serial, fix stale/missing API referencesdocs/pre-release-audit
Pre-release documentation audit against master. Adds the two fully undocumented modules and closes gaps found by diffing every docs/*.html page against its corresponding source: - New docs/unix.html and docs/serial.html (socket.unix stream/dgram and socket.serial were never documented), linked from index.html, introduction.html, socket.html and reference.html. serial.html notes the current lack of a baud/parity/flow-control API and includes an os.execute+stty workaround example. Both note Windows is unsupported. - socket.html: document headers.setcanonic, point to unix/serial modules. - tcp.html: document getfamily, setpeername/setsockname aliases. - udp.html: document getfamily, getfd/setfd, dirty; document the ipv6-multicast-hops/ipv6-unicast-hops aliasing as current (known-buggy) behavior rather than the originally intended semantics. - http.html: correct redirect text (301/302/303/307/308, was 301/302 only); document MAXHEADERLINE/MAXHEADERSIZE. - dns.html: document getnameinfo. - ltn12.html: document source.rewind and BLOCKSIZE. - installation.html: fix stale "LuaSocket 3.0" sample output to 3.1.0. - reference.html: index every anchor added above plus new Unix/Serial blocks.
Diffstat (limited to '')
-rw-r--r--docs/serial.html308
1 files changed, 308 insertions, 0 deletions
diff --git a/docs/serial.html b/docs/serial.html
new file mode 100644
index 0000000..8e123b0
--- /dev/null
+++ b/docs/serial.html
@@ -0,0 +1,308 @@
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4
5<head>
6<meta name="description" content="LuaSocket: Serial port support">
7<meta name="keywords" content="Lua, LuaSocket, Serial, Port, TTY, Library, Support">
8<title>LuaSocket: Serial port support</title>
9<link rel="stylesheet" href="reference.css" type="text/css">
10</head>
11
12<body>
13
14<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
15
16<div class="header">
17<hr>
18<center>
19<table summary="LuaSocket logo">
20<tr><td align="center"><a href="http://www.lua.org">
21<img width="128" height="128" border="0" alt="LuaSocket" src="luasocket.png">
22</a></td></tr>
23<tr><td align="center" valign="top">Network support for the Lua language
24</td></tr>
25</table>
26<p class="bar">
27<a href="index.html">home</a> &middot;
28<a href="index.html#download">download</a> &middot;
29<a href="installation.html">installation</a> &middot;
30<a href="introduction.html">introduction</a> &middot;
31<a href="reference.html">reference</a>
32</p>
33</center>
34<hr>
35</div>
36
37<!-- serial +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
38
39<h2 id="serial">Serial port support</h2>
40
41<p>
42The <tt>socket.serial</tt> module opens a serial device (e.g.
43<tt>/dev/ttyUSB0</tt>) and exposes it through the same buffered,
44timeout-aware <tt>send</tt>/<tt>receive</tt> interface used by
45<a href="tcp.html">TCP</a> and <a href="unix.html">Unix domain</a>
46stream objects.
47</p>
48
49<p class="note">
50Note: This module is only built on Unix-like platforms (Linux, macOS,
51BSD, Haiku). It is not available on Windows.
52</p>
53
54<p>
55Serial port support is a separate module that must be required
56explicitly. Unlike most other LuaSocket modules, it returns a
57<em>function</em> directly &mdash; the constructor &mdash; rather than a
58table of functions:
59</p>
60
61<pre class="example">
62-- loads the socket.serial module; note this is the constructor itself
63local serial_open = require("socket.serial")
64
65-- open the device
66local port = assert(serial_open("/dev/ttyUSB0"))
67port:settimeout(1)
68assert(port:send("AT\r\n"))
69print(port:receive())
70port:close()
71</pre>
72
73<p class="note">
74Note: <b>There is currently no API to configure the serial line itself
75&mdash; baud rate, parity, data/stop bits or flow control.</b> The device
76is opened non-blocking with whatever settings the OS driver or a prior
77external configuration (e.g. <tt>stty</tt>) left it in. This is a known
78current limitation of the module, not a deliberate protection against
79misuse; a future version may add a <tt>setoption</tt>-style API for these
80settings the way <a href="tcp.html#setoption"><tt>tcp:setoption</tt></a>
81does for TCP.
82</p>
83
84<p>
85Until such an API exists, the workaround is to configure the line with
86the platform's own <tt>stty</tt> utility (via <tt>os.execute</tt>)
87<em>before</em> opening the device with <tt>socket.serial</tt>:
88</p>
89
90<pre class="example">
91local serial_open = require("socket.serial")
92
93local dev = "/dev/ttyUSB0"
94
95-- Linux: stty -F &lt;device&gt; ...
96local ok = os.execute(string.format(
97 "stty -F %s 115200 cs8 -cstopb -parenb raw -echo", dev))
98
99-- macOS/BSD use -f instead of -F:
100-- os.execute(string.format("stty -f %s 115200 cs8 -cstopb -parenb raw -echo", dev))
101
102assert(ok, "failed to configure serial line with stty")
103
104local port = assert(serial_open(dev))
105port:settimeout(1)
106assert(port:send("AT\r\n"))
107print(port:receive())
108port:close()
109</pre>
110
111<p class="note">
112Note: <tt>raw -echo</tt> puts the line in raw mode, which matters for
113LuaSocket's framing: without it, the TTY driver applies its own line
114editing/echo, which can interfere with <a href="#receive"><tt>receive</tt></a>
115patterns and <a href="#send"><tt>send</tt></a> content. Adjust the
116<tt>stty</tt> flags (baud rate, parity, stop bits, flow control) to match
117your device; consult <tt>man stty</tt> for the full option set on your
118platform, since flag names and defaults vary between Linux, macOS and the
119BSDs.
120</p>
121
122<!-- close ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
123
124<p class="name" id="close">
125port:<b>close()</b>
126</p>
127
128<p class="description">
129Closes a serial object. No further operations (except further calls to
130<tt>close</tt>) are allowed on a closed object.
131</p>
132
133<p class="note">
134Note: Garbage-collected objects are automatically closed before
135destruction.
136</p>
137
138<!-- dirty +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
139
140<p class="name" id="dirty">
141port:<b>dirty()</b>
142</p>
143
144<p class="description">
145Check the read buffer status.
146</p>
147
148<p class="return">
149Returns <tt>true</tt> if there is any data in the read buffer,
150<tt>false</tt> otherwise.
151</p>
152
153<p class="note">
154Note: <b>This is an internal method, use at your own risk.</b>
155</p>
156
157<!-- getfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
158
159<p class="name" id="getfd">
160port:<b>getfd()</b>
161</p>
162
163<p class="description">
164Returns the underlying file descriptor associated to the object.
165</p>
166
167<p class="return">
168The descriptor.
169</p>
170
171<p class="note">
172Note: <b>This is an internal method. Unlikely to be portable. Use at your
173own risk.</b>
174</p>
175
176<!-- getstats ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
177
178<p class="name" id="getstats">
179port:<b>getstats()</b>
180</p>
181
182<p class="description">
183Returns accounting information on the port, useful for throttling of
184bandwidth. Works exactly like
185<a href="tcp.html#getstats"><tt>tcp:getstats</tt></a>.
186</p>
187
188<p class="return">
189The method returns the number of bytes received, the number of bytes
190sent, and the age of the object in seconds.
191</p>
192
193<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
194
195<p class="name" id="receive">
196port:<b>receive(</b>[pattern [, prefix [, maxsize]]]<b>)</b>
197</p>
198
199<p class="description">
200Reads data from the serial port, according to the specified <em>read
201pattern</em>. Works exactly like
202<a href="tcp.html#receive"><tt>tcp:receive</tt></a>, including the
203<tt>*a</tt>/<tt>*l</tt>/<tt>number</tt> patterns and the
204<tt>prefix</tt>/<tt>maxsize</tt> parameters.
205</p>
206
207<!-- send +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
208
209<p class="name" id="send">
210port:<b>send(</b>data [, i [, j]]<b>)</b>
211</p>
212
213<p class="description">
214Sends <tt>data</tt> through the serial port. Works exactly like
215<a href="tcp.html#send"><tt>tcp:send</tt></a>, including the optional
216<tt>i</tt>/<tt>j</tt> substring selection.
217</p>
218
219<!-- setfd ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
220
221<p class="name" id="setfd">
222port:<b>setfd(</b>fd<b>)</b>
223</p>
224
225<p class="description">
226Sets the underlying file descriptor associated to the object. The current
227one is simply replaced, not closed, and no other change to the object
228state is made.
229</p>
230
231<p class="return">
232No return value.
233</p>
234
235<p class="note">
236Note: <b>This is an internal method. Unlikely to be portable. Use at your
237own risk.</b>
238</p>
239
240<!-- setstats ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
241
242<p class="name" id="setstats">
243port:<b>setstats(</b>received, sent, age<b>)</b>
244</p>
245
246<p class="description">
247Resets accounting information on the port, useful for throttling of
248bandwidth. Works exactly like
249<a href="tcp.html#setstats"><tt>tcp:setstats</tt></a>.
250</p>
251
252<p class="return">
253The method returns 1 in case of success and <tt><b>nil</b></tt> otherwise.
254</p>
255
256<!-- settimeout ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
257
258<p class="name" id="settimeout">
259port:<b>settimeout(</b>value [, mode]<b>)</b>
260</p>
261
262<p class="description">
263Changes the timeout values for the object. Works exactly like
264<a href="tcp.html#settimeout"><tt>tcp:settimeout</tt></a>, including the
265'<tt>b</tt>' (block) and '<tt>t</tt>' (total) modes.
266</p>
267
268<!-- socket.serial +++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
269
270<p class="name" id="socket.serial">
271serial_open(<b>path</b>)
272</p>
273
274<p class="description">
275Opens the serial device at <tt>path</tt> and returns a serial object.
276This is the value returned directly by <tt>require("socket.serial")</tt>
277&mdash; there is no separate module table to index into, unlike
278<tt>socket.unix.stream()</tt> or <tt>socket.tcp()</tt>.
279</p>
280
281<p class="parameters">
282<tt>Path</tt> is a string with the device path (e.g.
283<tt>"/dev/ttyUSB0"</tt> or <tt>"/dev/ttyS0"</tt>).
284</p>
285
286<p class="return">
287In case of success, a new serial object is returned. In case of error,
288the function returns <b><tt>nil</tt></b>, followed by an error message,
289followed by the numeric <tt>errno</tt> value.
290</p>
291
292<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
293
294<div class="footer">
295<hr>
296<center>
297<p class="bar">
298<a href="index.html">home</a> &middot;
299<a href="index.html#download">download</a> &middot;
300<a href="installation.html">installation</a> &middot;
301<a href="introduction.html">introduction</a> &middot;
302<a href="reference.html">reference</a>
303</p>
304</center>
305</div>
306
307</body>
308</html>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-09-03 20:04:56 +0000