Update script API

README.md

@@ -371,22 +371,26 @@ Tio suppots Lua scripting to easily automate interaction with the tty device.
 In addition to the Lua API tio makes the following functions available:
 
 ```
-  expect(string, timeout)
+expect(string, timeout)
       Expect string - waits for string to match or timeout before continueing.
-
       Supports regular expressions. Special characters must be escaped with '\\'.
-
       Timeout is in milliseconds, defaults to 0 meaning it will wait forever.
 
-  send(string)
+      Returns 1 on successful match, 0 on timeout, or -1 on error.
+
+      On successful match it also returns the match string as second return value.
+
+send(string)
       Send string.
 
-  modem_send(file, protocol)
+      Returns number of bytes written on success or -1 on error.
+
+modem_send(file, protocol)
       Send file using x/y-modem protocol.
 
       Protocol can be any of XMODEM_1K, XMODEM_CRC, YMODEM.
 
-  tty_search()
+tty_search()
       Search for serial devices.
 
       Returns a table of number indexed tables, one for each serial device
@@ -396,38 +400,42 @@ In addition to the Lua API tio makes the following functions available:
 
       Returns nil if no serial devices are found.
 
-  exit(code)
+read(size, timeout)
-        Exit with code.
+      Read from serial device. If timeout is 0 or not provided it will wait
+      forever until data is ready to read.
 
-  high(line)
+      Returns number of bytes read on success, 0 on timeout, or -1 on error.
+
+exit(code)
+      Exit with exit code.
+
+high(line)
       Set tty line high.
 
-  low(line)
+low(line)
       Set tty line low.
 
-  toggle(line)
+toggle(line)
       Toggle the tty line.
 
-  sleep(seconds)
+sleep(seconds)
       Sleep for seconds.
 
-  msleep(ms)
+msleep(ms)
-        Sleep for milliseconds.
+      Sleep for miliseconds.
 
-  config_high(line)
+config_high(line)
       Set tty line state configuration to high.
 
-  config_low(line)
+config_low(line)
       Set tty line state configuration to low.
 
-  apply_config()
+apply_config()
-        Apply tty line state configuration.
+      Apply tty line state configuration. Using the line state configuration
+      API instead of high()/low() will help to make the lines physically switch as
+      simultaneously as possible. This may solve timing issues on some platforms.
 
-        Using the line state configuration API instead of high()/low() will
+Note: Line can be any of DTR, RTS, CTS, DSR, CD, RI
-        help to make the lines physically switch as simultaneously as possible.
-        This may solve timing issues on some platforms.
-
-  Note: Line can be any of DTR, RTS, CTS, DSR, CD, RI
 ```
 
 ### 3.4 Configuration file

man/tio.1.in

@@ -427,12 +427,15 @@ Expect string - waits for string to match or timeout before continueing.
 Supports regular expressions. Special characters must be escaped with '\\\\'.
 Timeout is in milliseconds, defaults to 0 meaning it will wait forever.
 
-Returns 1 on successful match, 0 on timeout, or -1 on invalid regular expression.
+Returns 1 on successful match, 0 on timeout, or -1 on error.
 
 On successful match it also returns the match string as second return value.
 
 .IP "\fBsend(string)"
 Send string.
+
+Returns number of bytes written on success or -1 on error.
+
 .IP "\fBmodem_send(file, protocol)"
 Send file using x/y-modem protocol.
 
@@ -448,6 +451,12 @@ following string indexed elements "path", "tid", "uptime", "driver",
 
 Returns nil if no serial devices are found.
 
+.IP "\fBread(size, timeout)"
+Read from serial device. If timeout is 0 or not provided it will wait forever
+until data is ready to read.
+
+Returns number of bytes read on success, 0 on timeout, or -1 on error.
+
 .IP "\fBexit(code)"
 Exit with exit code.
 .IP "\fBhigh(line)"

src/script.c

@@ -211,10 +211,6 @@ static int send(lua_State *L)
     }
 
     ret = write(device_fd, string, strlen(string));
-    if (ret < 0)
-    {
-        tio_error_print("%s\n", strerror(errno));
-    }
 
     lua_pushnumber(L, ret);
 
@@ -281,7 +277,7 @@ static int read_string(lua_State *L)
     char *buffer = malloc(size);
     if (buffer == NULL)
     {
-        ret = -3; // Read buffer allocation failed
+        ret = -1; // Error
         goto error;
     }
 
@@ -293,12 +289,12 @@ static int read_string(lua_State *L)
     ssize_t bytes_read = read_poll(device_fd, buffer, size, timeout);
     if (bytes_read < 0)
     {
-        ret = -1; // Read error
+        ret = -1; // Error
         goto error;
     }
     else if (bytes_read == 0)
     {
-        ret = -2; // Timeout
+        ret = 0; // Timeout
         goto error;
     }