2020-03-16 release

doc/quickjs.texi

@@ -373,44 +373,35 @@ optional properties:
 @item loadScript(filename)
 Evaluate the file @code{filename} as a script (global eval).
 
-@item Error(errno)
+@item loadFile(filename)
+Load the file @code{filename} and return it as a string assuming UTF-8
+encoding. Return @code{null} in case of I/O error.
 
-@code{std.Error} constructor. Error instances contain the field
-@code{errno} (error code) and @code{message} (result of
-@code{std.Error.strerror(errno)}).
+@item open(filename, flags, errorObj = undefined)
+Open a file (wrapper to the libc @code{fopen()}). Return the FILE
+object or @code{null} in case of I/O error. If @code{errorObj} is not
+undefined, set its @code{errno} property to the error code or to 0 if
+no error occured.
 
-The constructor contains the following fields:
+@item popen(command, flags, errorObj = undefined)
+Open a process by creating a pipe (wrapper to the libc
+@code{popen()}). Return the FILE
+object or @code{null} in case of I/O error. If @code{errorObj} is not
+undefined, set its @code{errno} property to the error code or to 0 if
+no error occured.
 
-  @table @code
-  @item EINVAL
-  @item EIO
-  @item EACCES
-  @item EEXIST
-  @item ENOSPC
-  @item ENOSYS
-  @item EBUSY
-  @item ENOENT
-  @item EPERM
-  @item EPIPE
-    Integer value of common errors (additional error codes may be defined).
-  @item strerror(errno)
-    Return a string that describes the error @code{errno}.
-  @end table
-
-@item open(filename, flags)
-Open a file (wrapper to the libc @code{fopen()}). Throws 
-@code{std.Error} in case of I/O error.
-
-@item popen(command, flags)
-Open a process by creating a pipe (wrapper to the libc @code{popen()}). Throws 
-@code{std.Error} in case of I/O error.
-
-@item fdopen(fd, flags)
+@item fdopen(fd, flags, errorObj = undefined)
 Open a file from a file handle (wrapper to the libc
-@code{fdopen()}). Throws @code{std.Error} in case of I/O error.
+@code{fdopen()}). Return the FILE
+object or @code{null} in case of I/O error. If @code{errorObj} is not
+undefined, set its @code{errno} property to the error code or to 0 if
+no error occured.
 
-@item tmpfile()
-Open a temporary file. Throws @code{std.Error} in case of I/O error.
+@item tmpfile(errorObj = undefined)
+Open a temporary file. Return the FILE
+object or @code{null} in case of I/O error. If @code{errorObj} is not
+undefined, set its @code{errno} property to the error code or to 0 if
+no error occured.
 
 @item puts(str)
 Equivalent to @code{std.out.puts(str)}.
@@ -431,6 +422,27 @@ Wrappers to the libc file @code{stdin}, @code{stdout}, @code{stderr}.
 @item SEEK_END
 Constants for seek().
 
+@item Error
+
+Enumeration object containing the integer value of common errors
+(additional error codes may be defined):
+
+  @table @code
+  @item EINVAL
+  @item EIO
+  @item EACCES
+  @item EEXIST
+  @item ENOSPC
+  @item ENOSYS
+  @item EBUSY
+  @item ENOENT
+  @item EPERM
+  @item EPIPE
+  @end table
+
+@item strerror(errno)
+Return a string that describes the error @code{errno}.
+
 @item gc()
 Manually invoke the cycle removal algorithm. The cycle removal
 algorithm is automatically started when needed, so this function is
@@ -453,12 +465,14 @@ optional properties:
   to be UTF-8 encoded.
 
   @item full
+  
   Boolean (default = false). If true, return the an object contains
   the properties @code{response} (response content),
   @code{responseHeaders} (headers separated by CRLF), @code{status}
-  (status code). If @code{full} is false, only the response is
-  returned if the status is between 200 and 299. Otherwise an
-  @code{std.Error} exception is raised.
+  (status code). @code{response} is @code{null} is case of protocol or
+  network error. If @code{full} is false, only the response is
+  returned if the status is between 200 and 299. Otherwise @code{null}
+  is returned.
 
   @end table
 
@@ -468,7 +482,7 @@ FILE prototype:
 
 @table @code
 @item close()
-Close the file.
+Close the file. Return 0 if OK or @code{-errno} in case of I/O error.
 @item puts(str)
 Outputs the string with the UTF-8 encoding.
 @item printf(fmt, ...args)
@@ -476,14 +490,21 @@ Formatted printf, same formats as the libc printf.
 @item flush()
 Flush the buffered file.
 @item seek(offset, whence)
-Seek to a give file position (whence is @code{std.SEEK_*}). Throws a
-@code{std.Error} in case of I/O error.
+Seek to a give file position (whence is
+@code{std.SEEK_*}). @code{offset} can be a number or a bigint. Return
+0 if OK or @code{-errno} in case of I/O error.
 @item tell()
 Return the current file position.
+@item tello()
+Return the current file position as a bigint.
 @item eof()
 Return true if end of file.
 @item fileno()
 Return the associated OS handle.
+@item error()
+Return true if there was an error.
+@item clearerr()
+Clear the error indication.
 
 @item read(buffer, position, length)
 Read @code{length} bytes from the file to the ArrayBuffer @code{buffer} at byte
@@ -545,7 +566,9 @@ POSIX open flags.
 Close the file handle @code{fd}.
 
 @item seek(fd, offset, whence)
-Seek in the file. Use @code{std.SEEK_*} for @code{whence}.
+Seek in the file. Use @code{std.SEEK_*} for
+@code{whence}. @code{offset} is either a number or a bigint. If
+@code{offset} is a bigint, a bigint is returned too.
 
 @item read(fd, buffer, offset, length)
 Read @code{length} bytes from the file handle @code{fd} to the
@@ -567,10 +590,10 @@ Return the TTY size as @code{[width, height]} or @code{null} if not available.
 Set the TTY in raw mode.
 
 @item remove(filename)
-Remove a file. Return 0 if OK or < 0 if error.
+Remove a file. Return 0 if OK or @code{-errno}.
 
 @item rename(oldname, newname)
-Rename a file. Return 0 if OK or < 0 if error.
+Rename a file. Return 0 if OK or @code{-errno}.
 
 @item realpath(path)
 Return @code{[str, err]} where @code{str} is the canonicalized absolute
@@ -581,10 +604,10 @@ Return @code{[str, err]} where @code{str} is the current working directory
 and @code{err} the error code.
 
 @item chdir(path)
-Change the current directory. Return the error code.
+Change the current directory. Return 0 if OK or @code{-errno}.
 
 @item mkdir(path, mode = 0o777)
-Create a directory at @code{path}. Return the error code.
+Create a directory at @code{path}. Return 0 if OK or @code{-errno}.
 
 @item stat(path)
 @item lstat(path)
@@ -613,10 +636,10 @@ Constants to interpret the @code{mode} property returned by
 
 @item utimes(path, atime, mtime)
 Change the access and modification times of the file @code{path}. The
-times are specified in milliseconds since 1970.
+times are specified in milliseconds since 1970. Return 0 if OK or @code{-errno}.
 
 @item symlink(target, linkpath)
-Create a link at @code{linkpath} containing the string @code{target}.
+Create a link at @code{linkpath} containing the string @code{target}. Return 0 if OK or @code{-errno}.
 
 @item readlink(path)
 Return @code{[str, err]} where @code{str} is the link target and @code{err}
@@ -685,7 +708,8 @@ object containing optional parameters:
   @end table
 
 @item waitpid(pid, options)
-@code{waitpid} Unix system call. Return the array @code{[ret, status]}.
+@code{waitpid} Unix system call. Return the array @code{[ret,
+status]}. @code{ret} contains @code{-errno} in case of error.
 
 @item WNOHANG
 Constant for the @code{options} argument of @code{waitpid}.