GAMBAS BOOK 3.19.1

A stream is to be understood as a data stream flowing between processes or a process and a data end connection.

Overview of the different types of data end connections, globally referred to as a file in Linux:

• Regular files (regular file).
• directories (directory)
• Symbolic links (symbolic link)
• Block-oriented devices (block device)
• Character-oriented devices (char device)
• Data links between processes according to the FIFO principle (named pipe)
• communication endpoints (unix-socket).

Notes:

• Regular files include the files you know as image or text files, for example.
• Directories are to be understood as containers for files.
• A symbolic link is a link to a file or directory.
• In the case of device files, a distinction is made between block-oriented devices such as RAM, hard disks, partitions or USB stick and character-oriented devices such as serial and parallel interfaces, terminal or sound interface. Under Linux, the device file /dev/stdin (file descriptor = 0) corresponds to standard input, the device file /dev/stdout (file descriptor = 1) to standard output and the device file /dev/stderr (file descriptor = 2) to standard error output. The standard error output is another output data stream to output error and status messages. Under Gambas, the device files (stdin, stdout and stderr) can be accessed via the static properties File.In, File.Out and File.Err provided in the File class. See Chapter “6.5 Class File” for an example of writing data to File.In and reading it from File.Out or File.Err.
• A named pipe is a volatile memory into which one process writes data and another reads the data from the named pipe. As volatile FIFO memory, it is therefore empty after data has been read out! A named pipe represents a simplex connection. You can either only read or write on a given pipe.
• Sockets embody the stream that is sent through them. If a socket is connected to another, it represents that stream. If a socket symbolises a stream of data from a connection to the Internet, then you are using a TCP socket for which you must specify a hostname and port. In contrast, with a Unix socket as a local socket, you only have to specify a path - a special file in the file system then belongs to the Unix socket. With the command ~ $ netstat -a -p –unix you can list the current local Unix sockets in a console - you will be surprised!

The interface stream specifies which methods are implemented. A stream has these four methods, among others:

Open,
Read file,
Write file,
Close.

The Stream class is the parent class for any Gambas object that represents a stream. This means that every class that inherits from the class Stream (gb) as a base class has at least these four methods. You cannot create this (base) class. Which functionality of a Stream object you can use depends on its exact class and also on the way the object is created.

For practical work, it is thus largely irrelevant whether you write data to or read data from, for example, a regular file, a serial port or a Unix socket.Here is the list of classes that inherit from the Stream class and are described in the Gambas book:

Compress    	Chapter 28.1.1
Uncompress  	Chapter 28.1.2
Process     	Chapter 21
SerialPort  	Chapter 24.1.5
Curl        	Chapter 24 (FTPClient and HTTPClient.)
File        	Chapter 6.5
Named Pipe	Chapter 6.2.1
Socket      	Chapter 24 (TCP- and Local-Unix-Socket)
VideoDevice 	Chapter 24

In Gambas, a Stream is an object that inherits from the Stream class (gb) and therefore implements its properties and methods. The Stream class has these properties:

Table 6.0.1.1 : Properties of the Stream class

The Stream class has these six methods:

Table 6.0.2.1 : Methods of the class Stream

The project in the download area demonstrates how to use the Type property of a Stat object to determine the type of file:

Figure 6.0.3.1.1: Determining the type of files

The characters -, d, l, b, c, p and s characterise the type of a file in the context of the command ls -l and displaying the output in a console.

Also in a console, you can use the file command to quickly determine what type of file a given file is:

Regular file
-------------------------------
hans@mint-183 ~ $ file nwm.xml
nwm.xml: exported SGML document, ASCII text

Directory
-------------------------
hans@mint-183 ~/BildTon $ file Fractals
Fractals: directory

Symbolic links
---------------------------------
hans@mint-183 ~/Schreibtisch $ file Formatting_DokuWiki_Tables
Formatting_DokuWiki_Tables: symbolic link to /home/hans/DW/0_DW_Convert/librewriter2dokuwiki.gambas

Blocked devices (block devices)
--------------------------------------
hans@mint-183 ~/Schreibtisch $ file /dev/sdd1
/dev/sdd1: block special (8/49)

Character-oriented devices (char devices)
---------------------------------------
hans@mint-183 ~ $ file /dev/ttyUSB0
/dev/ttyUSB0: character special (188/0)

Data links between processes (named pipe)
-------------------------------------------------
hans@mint-183 ~ $ mknod mypipe p 	' Generate Named Pipe
hans@mint-183 ~ $ file mypipe
mypipe: fifo (named pipe)
hans@mint-183 ~ $ rm mypipe	' Delete Named Pipe

Communication endpoint (unix socket)
------------------------------------
hans@mint-183 ~ $ file /run/user/1000/unix_socket.sock
/run/user/1000/unix_socket.sock: socket

For example, the documentation states.

FLUSH [ [ # ] Stream ]

where the # sign is marked as optional. In Gambas, you can prepend the # character to the variable name of a stream object, but only for the CLOSE, READ, WRITE, SEEK, INPUT, LINE INPUT, PRINT, UNLOCK and FLUSH instructions. This does not work in function calls like LOF(…), EOF(…) or the instruction LOCK.

In a Socket_Read event, you can use the following assignment, for example:

vData = Read #Last, -4096

In Last, the Socket object is returned that triggered the Read event and from which data can be read. You should prefer the “#Last” to “Last” because “Last” alone is not seen to be a stream in this case.