Add: NASL documentation for unsafe functions

doc/manual/nasl/built-in-functions/unsafe/file_close.md

@@ -0,0 +1,31 @@
+# file_close
+
+## NAME
+
+**file_close** - close a file descriptor
+
+## SYNOPSIS
+
+*Optional(int)* **file_close**(0: *int*);
+
+**file_close** takes one unnamed argument.
+
+## DESCRIPTION
+
+This function is used to close an opened file descriptor.
+
+The first positional argument contains the file descriptor as an *int* returned by **[file_open(3)](file_open.md)**.
+
+## RETURN VALUE
+
+Either 0 on success or *NULL* on failure
+
+## ERRORS
+
+first positional argument is either missing or negative
+
+closing the file descriptor failed
+
+## SEE ALSO
+
+**[file_open(3)](file_open.md)**

doc/manual/nasl/built-in-functions/unsafe/file_open.md

@@ -0,0 +1,44 @@
+# file_open
+
+## NAME
+
+**file_open** - opens a file descriptor
+
+## SYNOPSIS
+
+*int* **file_open**(name: *string*, mode: *string*);
+
+**file_open** takes two named arguments.
+
+## DESCRIPTION
+
+This function is used to open a file descriptor to be able to either read or write to a file on the host system.
+
+*name* is a *string* parameter. It contains the path of the file.
+
+*mode* is a *string* parameter. It contains the mode in which the file is opened. There are 5 modes:
+- r: read only
+- w: write only + create
+- w+: write only + truncate + create
+- a: write only + append + create
+- a+: read and write + append + create
+
+After done with the file, the descriptor hast to be closed with **[file_close(3)](file_close.md)**.
+
+## RETURN VALUE
+
+*int* representing the file descriptor or *NULL* on failure
+
+## ERRORS
+
+parameter *name* is missing
+
+parameter *mode* is missing
+
+unable to open file descriptor, see **open(2)** for further information
+
+unable to retrieve file stats, see **stat(2)** for further information
+
+## SEE ALSO
+
+**[file_close(3)](file_close.md)**

doc/manual/nasl/built-in-functions/unsafe/file_read.md

@@ -0,0 +1,43 @@
+# file_read
+
+## NAME
+
+**file_read** - read from a file
+
+## SYNOPSIS
+
+*string* **file_read**(fp: *int*, length: *int*);
+
+**file_read** takes two named arguments
+
+## DESCRIPTION
+
+This function is used to read data from a file.
+
+*fp* is an *int* parameter. It is the file descriptor for the file to read from. It is returned by **[file_open(3)](file_open.md)**.
+
+*length* is an *int* parameter. It determines the length of the data to read from the file
+
+With the function **[file_seek(3)](file_seek.md)** an offset can be set from where to start reading the file.
+
+## RETURN VALUE
+
+Data from the file as *string*
+
+## ERRORS
+
+missing or negative *fp* argument
+
+## EXAMPLES
+
+**1**: Open file descriptor, read file, close it
+```cpp
+fd = file_open(name: "foo/bar.txt", mode: "w");
+txt = file_read(fp: fd, length: 10);
+file_close(fd);
+# do some stuff with txt
+```
+
+## SEE ALSO
+
+**[file_open(3)](file_open.md)**, **[file_seek(3)](file_seek.md)**

doc/manual/nasl/built-in-functions/unsafe/file_seek.md

@@ -0,0 +1,33 @@
+# file_seek
+
+## Name
+
+**file_seek** - set offset for file operations
+
+## SYNOPSIS
+
+*int* **file_seek**(fp: *int*, offset: *int*);
+
+**file_seek** takes 2 named arguments
+
+## DESCRIPTION
+
+This function takes a file descriptor and applies an offset for operations on the file.
+
+*fp* is an *int* parameter. It is the file descriptor for the file to read from. It is returned by **[file_open(3)](file_open.md)**.
+
+*offset* is an *int* parameter. It determines the offset
+
+## RETURN VALUE
+
+0 on success, NULL on error
+
+## ERRORS
+
+*fd* parameter is missing or negative
+
+unable to apply the offset, see **lseek(2)** for more information
+
+## SEE ALSO
+
+**[file_open(3)](file_open.md)**

doc/manual/nasl/built-in-functions/unsafe/file_stat.md

@@ -0,0 +1,33 @@
+# file_stat
+
+## NAME
+
+**file_stat** - get size of a file
+
+## SYNOPSIS
+
+*int* **file_stat**(0: *string*);
+
+**file_stat** takes one positional argument
+
+## DESCRIPTION
+
+This function is used to get the size of a file.
+
+The first unnamed argument is the path to the file as *string*
+
+## RETURN VALUE
+
+The size of the file as *int* or *NULL* on failure
+
+## ERRORS
+
+first positional argument is missing
+
+## NOTES
+
+Currently it is not possible to get the cause of the failure
+
+## SEE ALSO
+
+**[file_open(3)](file_open.md)**

doc/manual/nasl/built-in-functions/unsafe/file_write.md

@@ -0,0 +1,40 @@
+# file_write
+
+## NAME
+
+**file_write** - writes data to a file
+
+## SYNOPSIS
+
+*int* **file_write**(fp: *int*, data: *string*);
+
+## DESCRIPTION
+
+This function writes to a opened file. In order to be able to write to a file it has to be opened with **[file_open(3)](file_open.md)** before.
+
+*fp* is an *int* parameter. It is the file descriptor for the file to write into
+
+*data* is a *string* parameter. It is the data, which is written into the file
+
+## RETURN VALUE
+
+number of written bytes, *NULL* on error and 0 on failure
+
+## ERRORS
+
+*fp* or *data* argument is missing
+
+unable to write data, see **write(2)** for more information
+
+## EXAMPLES
+
+**1**: Open file descriptor, write file, close it
+```cpp
+fd = file_open(name: "foo/bar.txt", mode: "w");
+file_write(fp: fd, data: "put some useful text in here");
+file_close(fd);
+```
+
+## SEE ALSO
+
+**[file_open(3)](file_open.md)**

doc/manual/nasl/built-in-functions/unsafe/find_in_path.md

@@ -0,0 +1,37 @@
+# find_in_path
+
+## NAME
+
+**find_in_path** - searches a command in $PATH and returns TRUE if found, or FALSE if not. It takes one string argument (the command name)
+
+## SYNOPSIS
+
+*boolean* **find_in_path**(0: *string*);
+
+**find_in_path** takes 1 positional argument.
+
+
+## DESCRIPTION
+
+This function is used to check if a command exists in $PATH on the scanner host system. If the command exists, this function returns a *TRUE* value, if not it return a *FALSE* value.
+
+The first positional argument is the command which is searched for.
+
+
+## RETURN VALUE
+
+*TRUE* if the command exists in $PATH, or *FALSE* if not
+
+
+## EXAMPLES
+
+**1**: Search for a command and run it
+```cpp
+if ( find_in_path("foo") ) {
+    out = pread(cmd: "foo", argv: NULL, cd: FALSE, drop_privileges_user: NULL);
+}
+```
+
+## SEE ALSO
+
+**[pread(3)](pread.md)**

doc/manual/nasl/built-in-functions/unsafe/fread.md

@@ -0,0 +1,31 @@
+# fread
+
+## NAME
+
+**fread** - read a whole file on the openvas-scanner host
+
+## SYNOPSIS
+
+*string* **fread**(0: *string*);
+
+**fread** takes 1 unnamed argument
+
+## DESCRIPTION
+
+This function is used to read a whole file in one go on the openvas-scanner host. It is not necessary to open/close a file descriptor.
+
+The first positional argument is of type *string* and is the path to the file.
+
+## RETURN VALUE
+
+content of file as *string*
+
+## ERRORS
+
+first positional argument is missing
+
+unable to read file, see *G_FILE_ERROR* for more information
+
+## SEE ALSO
+
+**[fwrite(3)](fwrite.md)**

doc/manual/nasl/built-in-functions/unsafe/fwrite.md

@@ -0,0 +1,35 @@
+# fwrite
+
+## NAME
+
+**fwrite** - write a file on the openvas-scanner host
+
+## SYNOPSIS
+
+*int* **fwrite**(data: *string*, file: *string*);
+
+**fwrite** takes 2 named arguments
+
+## DESCRIPTION
+
+This function is used to write a file on the openvas-scanner host. It is not necessary to open/close a file descriptor. If the file already exists, it gets overwritten.
+
+*data* is a *string* parameter. It contains the data, which is written into a file.
+
+*file* is a *string* parameter. It contains the path to the file to write to.
+
+## RETURN VALUE
+
+number of bytes written to the file as *int*
+
+## ERRORS
+
+parameter *data* is missing
+
+parameter *file* is missing
+
+unable to write file, see *G_FILE_ERROR* for more information
+
+## SEE ALSO
+
+**[fread(3)](fread.md)**

doc/manual/nasl/built-in-functions/unsafe/get_tmp_dir.md

@@ -0,0 +1,43 @@
+# get_tmp_dir
+
+## NAME
+
+**get_tmp_dir** - get a path to temporary directory
+
+## SYNOPSIS
+
+*string* **get_tmp_dir**();
+
+## DESCRIPTION
+
+This function gets the directory to use for temporary files.
+
+On UNIX, this is taken from the *TMPDIR* environment variable. If the variable is not set, *P_tmpdir* is used, as defined by the system C library. Failing that, a hard-coded default of "/tmp" is returned.
+
+If the access to this directory is denied, the function fails and *NULL* is returned.
+
+This is useful to write temporary date onto the scanner host system.
+
+## RETURN VALUE
+
+Path to the directory as *string* or *NULL* on failure
+
+## ERRORS
+
+no access to the temporary directory
+
+## EXAMPLES
+
+**1**: Get path to tmp directory and create file
+```cpp
+path = get_tmp_dir();
+if(path) {
+    fd = file_open(name: path, mode: "w");
+    # do some stuff with new file
+    file_close(fd)
+}
+```
+
+## SEE ALSO
+
+**[file_open(3)](file_open.md)**, **[file_close(3)](file_close.md)**

doc/manual/nasl/built-in-functions/unsafe/index.md

@@ -0,0 +1,7 @@
+# "unsafe" Functions
+
+## GENERAL
+
+"unsafe" functions are working with the scanner host file system. It is possible to open, read and write files as well as run commands.
+
+## TABLE OF CONTENT