20 Files, Sockets, and Pipes: Open

This chapter gives reference documentation for the Open module. The module contains the following classes:

  1. Open.file for reading and writing files.

  2. Open.socket for Internet socket connections.

  3. Open.pipe for creation of operating system processes.

  4. Open.text for reading and writing text line by line and character by character. It is a mixin class that can be combined with any of the classes of the Open module.

A tutorial account on open programming can be found in ``Open Programming in Mozart''.

20.1 Exceptions

The methods of any of the Open module classes can raise different exceptions.

operating system

When an operating system exception occurs the Oz exception defined in the module OS is raised.

already initialized

An exception of the format

system(open(alreadyInitialized O M) debug:X)

is raised if an already initialized object O is initialized again by applying it to the message M.

already closed

An exception of the format

system(open(alreadyClosed O M) debug:X)

is raised if a method other than close of an already closed object O is applied. M is as above the message the object has been applied to.

illegal flags

An exception of the format

system(open(illegalFlags O M) debug:X)

is raised if an object O is initialized with an unknown flag. M is the initialization message.

ilegal modes

An exception of the format

system(open(illegalModes O M) debug:X)

is raised if an object O is initialized with an unknown mode. M is the initialization message.

name or URL

An exception of the format

system(open(nameOrUrl O M) debug:X)

is raised if an object O is initialized with both a name and an URL or with neither. M is the initialization message.

URL is read-only

An exception of the format

system(open(urlIsReadOnly O M) debug:X)

is raised if an object O is initialized with an URL and the write flag. M is the initialization message.

20.2 The Class Open.file

The class Open.file has the following public methods.

init

init(name: +NameV 
     flags:
+FlagsAs <= [read]
     mode: 
+ModeR   <= mode(owner:[write] all:[read]))
init(url:  
+UrlV 
     flags:
+FlagsAs <= [read]
     mode: 
+ModeR   <= mode(owner:[write] all:[read]))

Initializes the file object and associates it with a Unix file.

NameV is either a valid filename or one of the atoms stdin, stdout, and stderr. In this case, the standard input, standard output, or standard error stream is opened, respectively.

In addition to using a filename to open a file also a url UrlV can be used. Only one of the features name or url is allowed.

The value of FlagsAs must be a list, with its elements chosen from the following atoms:

read, write, append, create, truncate, exclude, text, binary

For reading a file, the atom read must be included in FlagsAs. Similarly, the atom write must be included for writing. It is possible to include both atoms, giving both read and write access to the file. For files attached to an url, only reading access is possible.

Atom text opens a file in text mode. This is important on platforms (e. g. Windows) where the line ends are represented on disk by CRLF rather than just LF. On such platforms, when a file is opened in text mode, the conversion from CRLF to LF on reading (and in the reverse direction on writing) happens automatically. Atom binary opens a file in binary mode, where no such translation happens. On other platforms (e. g. Linux), these flags have no effect.

When a file object is opened, the seek pointer, pointing to the current position in the file, is initialized to point to the start of the file. Any subsequent read or write takes place at the position given by this pointer.

The remaining atoms make sense only if the file is opened for writing. If the atom append is included, the seek pointer is moved to the end of the file prior to each attempt to write to the file.

If the file to be opened already exists, the presence of the atom create has no effect. Otherwise, the file is created. Including truncate resets the length of an existing file to zero and discards its previous content.

An attempt to open an existing file fails, if exclude is contained. Thus, this flag grants exclusive access of the file object to the operating system file.

If the file is opened for writing and the atom create is included, the access rights are set as specified by ModeR. This must be a record with fields drawn from all, owner, group and others. Its subterms must be lists of the atoms read, write and execute.

More detailed information can be found in open(2), chmod(2), and umask(2).

read

read(list: ?ListS   
     tail: 
TailX   <= nil   
     size: 
+SizeAI <= 1024   
     len:  
?LenI   <= _) 

Reads data from a file. SizeAI specifies how much data should be read from the file. If the field len is present, LenI is bound to the number of bytes actually read. LenI may be less than SizeAI. The atom all is also a legal value for SizeAI. In this case the entire file is read.

The data read binds ListS to a list of characters. The tail of the list can be given by TailX. The value for TailX defaults to nil, which means that in this case the list ListS is a string.

See also read(2).

write

write(vs:  +V  
      len: 
?I <= _)

Writes the virtual string V to a file.

See write(2).

seek

seek(whence: +WhenceA <= set   
     offset: 
+OffsetI <= 0)

Sets the file object's seek pointer

Allowed values for WhenceA are the atoms set, current, or 'end'.

In case of set the position of the seek pointer is moved to the absolute position from the beginning of the file given by the value of OffsetI.

In case of current the pointer is moved ahead by OffsetI. Notice, that the pointer can be moved backward by a negative OffsetI, and forward by a positive OffsetI.

If 'end' is given, the pointer is moved by OffsetI with respect to the current end of the file.

In particular, invoking seek with the default parameters moves the pointer to the beginning of the file.

See lseek(2).

tell

tell(offset: ?OffsetI)

Returns the current position of the seek pointer counting from the beginning of the file.

See lseek(2).

close

close

Closes the file object as well as the file.

See close(2).

dOpen

dOpen(+ReadFileDescI +WriteFileDescI)

Danger

Initializes the object. ReadFileDescI and WriteFileDescI must be integers of already open file descriptors (in the usual operating system sense). Note that this method should only be used for advanced purposes.

getDesc

getDesc(?ReadFileDescIB ?WriteFileDescIB)

Danger

Returns the internally used file descriptors.

If the object is not yet initialized, ReadFileDescIB and WriteFileDescIB are bound to false, otherwise to the respective integers. Note, that this method is only for advanced purposes.

20.3 The Class Open.socket

The class Open.socket has the following public methods.

init

init(type:     +TypeA  <= stream
     protocol: 
+ProtoV <= "" 
     time:     
+TimeI  <= ~1)                

Initializes a socket object.

The type of the socket TypeA determines the type of the socket, which can be either stream or datagram.

The protocol is described by ProtoV where the empty string "" means to choose an appropriate protocol automatically. Other possible values are the TCP protocol (you have to give "tcp") for stream sockets, and UDP (you have to give "udp") for datagram sockets.

The integer TimeI specifys for how long a time (in milliseconds) the socket attempts to accept a connection. The value ~1 means infinite time. See the following description of the accept method for more details.

See also socket(2).

bind

bind(takePort: +TakePortI <= _   
     port:     
?PortI     <= _)

Names a socket globally.

If the field takePort is present, its value is chosen for binding. Otherwise, a fresh port number value is generated by the object. This port number is accessible at the field port.

See also bind(2).

listen

listen(backLog: +LogI <= 5)

Signals that a socket is willing to accept connections.

LogI describes the maximum number of pending connections to be buffered by the system.

See also listen(2).

accept

accept(accepted:    ?Object  <= _
       acceptClass: 
+Class    <= _   
       host:        
?HostSB   <= _   
       port:        
?PortIB   <= _)  

Accepts a connection from another socket.

The method suspends until a connection has been accepted or the number of milliseconds as specified by the time value in the init method has elapsed. After this period, no connection will be accepted, and both PortIB and HostSB are bound to false.

If a connection is accepted within the given time, the following happens: HostSB and PortIB are bound accordingly if their fields are present.

If the fields accepted and acceptClass are present, Object is bound to an object created from the class Class. Class must be a sub class of Open.socket. Then the accepted connection is available with Object.

Otherwise, the access to the socket at which the connection was accepted, because any subsequent message will refer to the accepted socket connection.

See also accept(2).

connect

connect(host: +HostV <= localhost
        port: 
+PortI)

Connects to another socket.

The address of the socket to connect to is given by HostV and PortI.

Danger

Be very careful in using this method: it blocks the entire Oz system until it succeeds.

See connect(2).

server

server(port: ?PortI   
       host: 
?HostV <= localhost)

Initializes a stream socket as a server.

client

client(port: +PortI   
       host: 
+HostV <= localhost)

Initializes a stream socket as a client.

read

read(list: ?ListS   
     tail: 
TailX  <= nil   
     size: 
+SizeAI <= 1024   
     len:  
?LenI  <= _)

Receives data from a stream-connected socket or from a datagram socket with peer specified.

An attempt is made to read SizeAI bytes from the socket. ListS is constrained to the data while the tail of ListS is constrained to TailX. The atom all is also a legal value for SizeAI. In this case the entire input is read.

LenI is bound to the number of bytes actually read. If the socket is of type stream and the other end of the connection has been closed LenI is bound to 0.

See also read(2).

receive

receive(list: ?ListS   
        tail: 
TailX  <= nil   
        len:  
?LenI  <= _  
        size: 
+SizeI <= 1024  
        host: 
?HostS <= _   
        port: 
?PortI <= _)

Receives data from a socket.

An attempt is made to read SizeI bytes from the socket. ListS is bound to the data while the tail of the list is bound to TailX.

LenI is bound to the number of bytes actually read. If the socket is of type stream and the other end of the connection has been closed LenI is bound to 0.

The source of the data is signaled by binding HostS and PortI.

See also recvfrom(2).

write

write(vs:  +V 
      len: 
?I <= _)

Writes the virtual string V to a stream-connected socket or to a datagram socket with peer specified.

I is bound to the number of characters written.

See also write(2).

send

send(vs:  +V 
     len: 
?I <= _)
send(vs:   
+V 
     len:  
?I     <= _
     port: 
+PortI   
     host: 
+HostV <= localhost)

Sends data as specified by V to a socket.

The destination of the data may be given by HostV and PortI. If they are omitted, the data is sent to the peer of a datagram socket or to the other end of a connection in case of a stream socket. I is bound to the number of characters written.

See also send(2).

shutDown

shutDown(how: +HowAs <= [receive send])

Disallows further actions on the socket.

HowAs has to be a non-empty list which must contain only the atoms receive and send. The atom send signals that no further data transmission is allowed, while receive signals that no further data reception is allowed.

See also shutdown(2).

close

close

Closes the socket.

See also close(2)

flush

flush(how: +HowAs <= [receive send])

Blocks until all requests for reading, receiving, writing, and sending have been fulfilled.

HowAs must be a non-empty list which may include the atoms receive and send. The atom send signals that the method should block until all send (or write) requests are fulfilled, while receive signals the same for receive (or read).

dOpen

dOpen(+ReadFileDescI +WriteFileDescI)

Danger

Initializes the object. ReadFileDescI and WriteFileDescI must be integers of already open file descriptors (in the usual operating system sense).

Note that this method should only be used for advanced purposes.

getDesc

getDesc(?ReadFileDescIB ?WriteFileDescIB)

Danger

Returns the internally used file descriptors.

If the object is not yet initialized, ReadFileDescIB and WriteFileDescIB are bound to false, otherwise to the respective integers.

Note, that this method is only for advanced purposes.

20.4 The Class Open.pipe

The class Open.pipe has the following public methods.

init

init(cmd:  +CmdV   
     args: 
+ArgsVs <= nil   
     pid:  
?PidI   <= _)

Initilizes the object and forks a process with process identification PidI executing the command CmdV with arguments ArgsVs.

The environment of the forked process is inherited from the process which runs the Oz Emulator. The standard input of the forked process is connected to sending and writing data, the standard output and standard error to reading and receiving data.

See also execv(3), fork(2).

read

read(list: ?ListS   
     tail: 
TailX  <= nil   
     size: 
+SizeAI <= 1024   
     len:  
?LenI  <= _)

Reads data ListS from the standard output or standard error of the forked process.

An attempt is made to read SizeI bytes. ListS is bound to the data read while the tail of ListS is bound to TailX. The atom all is also a legal value for SizeAI. In this case the entire input is read.

LenI is bound to the number of bytes actually read. If the socket is of type stream and the other end of the connection has been closed LenI is bound to 0.

See also read(2).

write

write(vs:  +V 
      len: 
?I <= _)

Writes the virtual string V to the standard input of the forked process.

I is bound to the number of characters written.

See also write(2).

flush

flush(how: +HowAs <= [receive send])

Blocks until all requests for reading and writing have been performed.

HowAs must be a non-empty list which may include the atoms receive and send. The atom send signals that the method should block until all write requests are fulfilled, while receive signals the same for read.

close

close(+KillB<=false)

Closes the object.

If KillB is false (the default) the method blocks until all pending read and write requests have been executed. If the started process is still running, it is killed by sending the SIGTERM signal. However, note that the inverse direction is not supported, which means the object is not automatically closed if the process terminates.

If KillB is true the possibly running process is immediately terminated by sending the SIGKILL signal.

See also wait(2) and kill(1).

dOpen

dOpen(+ReadFileDescI +WriteFileDescI)

Danger

Initializes the object. ReadFileDescI and WriteFileDescI must be integers of already open file descriptors (in the usual operating system sense).

Note that this method should only be used for advanced purposes.

getDesc

getDesc(?ReadFileDescIB ?WriteFileDescIB)

Danger

Returns the internally used file descriptors.

If the object is not yet initialized, ReadFileDescIB and WriteFileDescIB are bound to false, otherwise to the respective integers.

Note that this method is only for advanced purposes.

20.5 The Class Open.text

The mixin class Open.text has the methods listed below. Note, however, that it does not automatically cause a file to be opened in text mode; that must be done explicitly in the init method by supplying text as one of the flags.

getC

getC(?I)

Returns the next character, or false if the input is at the end.

Note that if an object is created that inherits from both Open.text and Open.file, the methods read and seek from the classes Open.file, Open.socket, and Open.pipe and do not work together with this method.

putC

putC(+I)

Writes the character I.

unGetC

unGetC

The last character read is written back to the input buffer and may be used again by getC. It is allowed only to unget one character.

getS

getS(?SB)

Returns the next line of the input as string, or false if the input is at the end. SB does not contain the newline character.

Note that if an object is created that inherits from both Open.text and Open.file, the methods read and seek from the class Open.file, Open.socket, and Open.pipe do not work together with this method.

putS

putS(+V)

Writes the virtual string V. Note that a newline character is appended.

atEnd

atEnd(?B)

Tests whether the end of input is reached.

dOpen

dOpen(+ReadFileDescI +WriteFileDescI)

Danger

Initializes the object. ReadFileDescI and WriteFileDescI must be integers of already open file descriptors (in the usual operating system sense).

Note that this method should only be used for advanced purposes.

getDesc

getDesc(?ReadFileDescIB ?WriteFileDescIB)

Danger

Returns the internally used file descriptors.

If the object is not yet initialized, ReadFileDescIB and WriteFileDescIB are bound to false, otherwise to the respective integers.

Note that this method is only for advanced purposes.


Denys Duchier, Leif Kornstaedt, Martin Homik, Tobias Müller, Christian Schulte and Peter Van Roy
Version 1.4.0 (20080702)