diff --git a/nselib/nmap.luadoc b/nselib/nmap.luadoc index 0d80a7fc4..70e8801b9 100644 --- a/nselib/nmap.luadoc +++ b/nselib/nmap.luadoc @@ -146,7 +146,7 @@ function get_interface_link(interface_name) -- lock, and release the mutex. The returned function takes only one argument, -- which must be one of -- * "lock": makes a blocking lock on the mutex. If the mutex is busy then the thread will yield and wait. The function returns with the mutex locked. --- * "trylock": makes a non-blocking lock on the mutex. If the mutex is busy then it immediately returns with a return value of false. Otherwise, the mutex locks the mutex and returns true. +-- * "trylock": makes a non-blocking lock on the mutex. If the mutex is busy then it immediately returns a false value. Otherwise, the mutex locks the mutex and returns true. -- * "done": releases the mutex and allows another thread to lock it. If the thread does not have a lock on the mutex, an error will be raised. -- * "running": returns the thread locked on the mutex or nil if no thread is locked. This should only be used for debugging as it interferes with finished threads from being collected. -- @param object Object to create a mutex for. @@ -181,9 +181,9 @@ function mutex(object) -- before the script terminates. -- -- A function that may raise an exception must follow the return protocol --- understood by this function: on an exception its return values are false --- followed by an error message; on success its return values are true followed --- by any other results. +-- understood by this function: on an exception its return values are +-- false or nil followed by an error message; on +-- success its return values are any true value followed by any other results. -- @param handler User cleanup function (optional). -- @usage -- local result, socket, try, catch @@ -227,9 +227,10 @@ function new_socket() -- "tcp", "udp" or "ssl"; it is -- "tcp" if not specified. -- --- On success the function returns true. On failure it returns false and an --- error string. Those strings are taken from the gai_strerror C --- function. They are (with the error code in parentheses): +-- On success the function returns a true value. On failure it returns a false +-- value (false or nil) and an error string. Those +-- strings are taken from the gai_strerror C function. They are +-- (with the error code in parentheses): -- * "Address family for hostname not supported" (EAI_ADDRFAMILY) -- * "Temporary failure in name resolution" (EAI_AGAIN) -- * "Bad value for ai_flags" (EAI_BADFLAGS) @@ -252,15 +253,19 @@ function new_socket() -- @return Status (true or false). -- @return Error code (if status is false). -- @see new_socket --- @usage local status, err = socket:connect(host.ip, port, "udp") +-- @usage +-- local status, err = socket:connect(host.ip, port, "udp") +-- if not status then +-- return string.format("Can't connect: %s", err) +-- end function connect(hostid, port, protocol) --- Sends data on an open socket. -- -- This socket method sends the data contained in the data string through an --- open connection. On success the function returns true. If the send operation --- has failed, the function returns true along with an error string. The error --- strings are +-- open connection. On success the function returns a true value. If the send +-- operation fails, the function returns a false value (false or +-- nil) along with an error string. The error strings are -- * "Trying to send through a closed socket": There was no call to socket:connect before the send operation. -- * "TIMEOUT": The operation took longer than the specified timeout for the socket. -- * "ERROR": An error occurred inside the underlying Nsock library. @@ -278,11 +283,11 @@ function send(data) -- -- The receive method does a non-blocking receive operation on an open socket. -- On success the function returns true along with the received data. On --- failure the function returns false along with an error string. A failure --- occurs for example if receive is called on a closed socket. The --- receive call returns to the NSE script all the data currently stored in the --- receive buffer of the socket. Error conditions are the same as for --- send. +-- failure the function returns a false value (false or +-- nil) along with an error string. A failure occurs for example if +-- receive is called on a closed socket. The receive call returns +-- to the NSE script all the data currently stored in the receive buffer of the +-- socket. Error conditions are the same as for send. -- @return Status (true or false). -- @return Data (if status is true) or error string (if status is false). -- @see new_socket @@ -299,9 +304,7 @@ function receive() -- returned, not just n. Use stdnse.make_buffer to -- guarantee only one line is returned per call. -- --- On success the function returns true along with the received data. If --- receiving data has failed, the function returns false along with an error --- string. Error conditions are the same as for send. +-- The return values and error codes are the same as for send. -- @param n Minimum number of lines to read. -- @return Status (true or false). -- @return Data (if status is true) or error string (if status is false). @@ -317,9 +320,7 @@ function receive_lines(n) -- even one is received then it is returned. If no characters arrive before the -- operation times out, a "TIMEOUT" error occurs. -- --- On success the function returns true along with the received data. If --- receiving data has failed, the function returns false along with an error --- string. Error conditions are the same as for send. +-- The return values and error codes are the same as for send. -- @param n Minimum number of bytes to read. -- @return Status (true or false). -- @return Data (if status is true) or error string (if status is false). @@ -350,9 +351,9 @@ function receive_bytes(n) -- received data (true) or discarded (false). -- -- On success the function returns true along with the received data. On failure --- the function returns false along with an error string. Possible error --- messages are the same as those that the other receive functions can return, --- with the addition of +-- the function returns false or nil along with an +-- error string. Possible error messages are the same as those that the other +-- receive functions can return, with the addition of -- * "Error inside splitting-function": The first argument was a function which caused an error while being called. -- * "Error in string.find (nsockobj:receive_buf)!": A string was provided as the first argument, and string.find() yielded an error while being called. -- * "Expected either a function or a string!": The first argument was neither a function nor a string. @@ -370,9 +371,9 @@ function receive_buf(delimiter, keeppattern) --- Closes an open connection. -- -- On success the function returns true. If the close fails, the function --- returns false and an error string. Currently the only error message is --- "Trying to close a closed socket", which is issued if the --- socket has already been closed. +-- returns false or nil and an error string. Currently +-- the only error message is "Trying to close a closed socket", +-- which is issued if the socket has already been closed. -- -- Sockets are subject to garbage collection. Should you forget to close a -- socket, it will get closed before it gets deleted (on the next occasion Lua's @@ -387,12 +388,12 @@ function close() --- Gets information about a socket. -- -- This function returns information about a socket object. It returns five --- values. If an error occurred, the first value is nil and the --- second value is an error string. Otherwise the first value is true and the --- remaining 4 values describe both endpoints of the TCP connection. If you put --- the call inside an exception handler created by new_try the --- status value is consumed. The call can be used for example if you want to --- query an authentication server. +-- values. If an error occurred, the first value is false or +-- nil and the second value is an error string. Otherwise the first +-- value is true and the remaining 4 values describe both endpoints of the TCP +-- connection. If you put the call inside an exception handler created by +-- new_try the status value is consumed. The call can be used for +-- example if you want to query an authentication server. -- @return Status (true or false). -- @return Local IP address (if status is true) or error string (if status is -- false).