Class: Socket

• Inheritance
• Description
• Class protocol
  • Compatibility-ST80
  • Compatibility-Squeak
  • Compatibility-VW
  • Signal constants
  • debugging
  • defaults
  • instance creation
  • obsolete
  • obsolete host queries
  • queries
• Instance protocol
  • Compatibility-Dolphin
  • Compatibility-ST80
  • Compatibility-Squeak
  • accepting connections
  • binding
  • closing
  • connecting
  • datagram transmission
  • error reporting
  • finalization
  • initialization
  • low level
  • printing & storing
  • queries
  • socket setup
  • specials
  • waiting
• Examples

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--NonPositionableExternalStream
                        |
                        +--Socket

Package:

stx:libbasic2

Category:

Streams-External

Version:

rev: 1.371 date: 2019/06/06 23:45:51

user: cg

file: Socket.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Author:

Claus Gittinger

Description:

This class provides access to sockets for interprocess communication.

Currently, only IP and UNIX domain sockets are really fully
tested and supported.
Code for appletalk is included, but was never tested ...
More may be added in the future.
(the code is prepared for things like SNA or decNet;
 however, right now, this code is empty and needs a little work.
 Implementing those is pretty straightforward, once the address
 data structures are known.)

Due to historic reasons (I started this class, before I got hold of some
code using ST-80 Sockets i.e. RemoteInvocation), there is some old interface
which is still supported.
This may vanish; use the #family:type: or #newTCPxxx and #newUDPxxx interfaces,
together with the bind/listen and accept calls,
which are meant to be compatible to ST-80's UnixSocketAccessor interface.

TODO: cleanup historic leftovers,
      change to raise more signals on errors.

Class protocol:

 family: domainSymbol type: typeSymbol

create a socket for domain and type - ST80 simply uses a different name.
Domain must be one of the symbols: #inet, #unix, #appletalk or #ns;
Type must be #stream, #datagram or #raw.

usage example(s):

Socket family:#AF_INET type:#stream Socket family:#AF_INET type:#datagram Socket family:#AF_UNIX type:#stream

 getHostname

return the computer's hostname string

 sockStream

return the type code for stream sockets

 deadlineSecs: seconds

 initializeNetwork

intentionally left blank here

 openConnectionToHostNamed: hostName port: portNr

 standardDeadline

a standard timeout in seconds for connection setup;
not really used in ST/X code (but by some code ported from squeak)

 standardTimeout

a standard timeout in seconds for transfers;
not really used in ST/X code (but by some code ported from squeak)

 wildcardPort

 AF_INET

 SOCK_STREAM

 brokenConnectionSignal

return the signal used to tell broken connections.
Since in unix, this is the same as the broken pipe signal,
return that one.
(for other Operatingsystems, this may change ..)

 invalidArgumentsSignal

dummy for compatibility

 debug: aBoolean

turn on/off internal debugprints.
This method is for ST/X debugging only and
may be removed in later versions

usage example(s):

Socket debug:true Socket debug:false

 defaultIpDomainForConnect

answer the domain used to look up host names for connect:
#AF_INET use only IPv4
#AF_INET6 use only IPv6
nil use both IPv4 and IPv6

 bindTo: aSocketAddress type: aTypeSymbol

create a socket for a specific type
and bind it to aSocketAddress.
Type must be:
#stream, #datagram or #raw

Neither connect nor connect-wait is done.

usage example(s):

Socket bindTo:(IPSocketAddress anyHost port:8081) type:#stream. Socket bindTo:(IPv6SocketAddress anyHost port:8081) type:#datagram.

 domain: domainSymbol type: type

create a socket for domain and type -
neither any connect nor binding is done.
Domain must be one of the symbols:
#inet, #unix, #appletalk, #decnet, #xns, ...;
Type must be:
#stream, #datagram or #raw

XXX: currently only the #AF_INET and #AF_INET6 and #AF_UNIX domains are supported

usage example(s):

Socket domain:#AF_INET type:#stream Socket domain:#AF_INET type:#datagram Socket domain:#AF_INET6 type:#stream Socket domain:#AF_INET6 type:#datagram Socket domain:#AF_UNIX type:#stream

 newIPv6

create an IPv6 socket - no binding or other setup is done,
neither connect nor connect-wait is done.

usage example(s):

Socket newIPv6

 newIPv6: portNrOrServiceName

create an IPv6 socket for a service -
neither connect nor connect-wait is done.

usage example(s):

(Socket newIPv6:9996). test (eval the code below, then open a browser on (replace by your own IPv6 address) http://[2003:a:e4d:bb01:a17f:9312:54cb:fed7]:9997/ (Socket newIPv6:9997) listenFor:1; readWait; accept.

 newTCP

create a TCP socket - no binding or other setup is done,
neither connect nor connect-wait is done.

usage example(s):

Socket newTCP

 newTCP: portNrOrServiceName

create a TCP socket for a service -
neither connect nor connect-wait is done.

usage example(s):

Socket newTCP:'http-alt'. Socket newTCP:9996.

 newTCPclientToAddress: aHostAddress port: aService

create a new TCP client socket connecting to a service.
Return a socket instance if ok, nil on failure.
Block until a connection is established (but only the current thread;
not the whole smalltalk).
See also: #newTCPclientToAddress:port:withTimeout:

 newTCPclientToAddress: aSocketAddressOrByteArray port: aService withTimeout: milliSecondsOrTimeDuration

create a new TCP client socket connecting to a service.
Return a socket instance if ok, nil on failure.
If the millis arg is nonNil, stop trying to connect after that many milliseconds
and return nil.

 newTCPclientToAddress: aSocketAddress withTimeout: milliSecondsOrTimeDuration

create a new TCP client socket connecting to a service.
Return a socket instance if ok, nil on failure.
If the millis arg is nonNil, stop trying to connect after that many milliseconds
and return nil.

usage example(s):

self newTCPclientToAddress:(IPv6SocketAddress hostName:'www.exept.de' port:80) withTimeout:nil

 newTCPclientToHost: hostNameOrAddress port: aPortOrServiceName

create a new TCP client socket connecting to a service.
If hostNameOrAddress is a string, try all the resolved addresses regardless
whether for IPv4 or IPv6.
Return a socket instance if ok, nil on failure.
Block until a connection is established (but only the current thread;
not the whole smalltalk).
See also: #newTCPclientToHost:port:withTimeout:

usage example(s):

Socket newTCPclientToHost:'www.exept.de' port:'https'

 newTCPclientToHost: hostNameOrAddress port: aPortOrServiceName domain: aDomainSymbolOrNil withTimeout: milliSecondsOrTimeDuration

create a new TCP client socket connecting to a service on hostNameOrAddress.
If hostNameOrAddress is a string, try all the resolved addresses.
Return a socket instance if ok, nil on failure.
Set aDomainSymbolOrNil to #AF_INET of #AF_INET6 to connect via a defined protocol.
Set aDomainSymbolOrNil to nil, to try all protocols.
If the milliSecondsOrTimeDuration arg is nonNil, stop trying to connect after that many milliSecondsOrTimeDurationeconds
and return nil.

 newTCPclientToHost: hostNameOrAddress port: aPortOrServiceName withTimeout: milliSecondsOrTimeDuration

create a new TCP client socket connecting to a service on hostNameOrAddress.
If hostNameOrAddress is a string, try all the resolved addresses regardless
whether for IPv4 or IPv6.
Return a socket instance if ok, nil on failure.
If the millis arg is nonNil, stop trying to connect after that many milliseconds
and return nil.

 newTCPserverAtAnonymousPort

create a new TCP server socket providing service on
a new anonymous port. The portNr is assigned by the OS.

 newTCPserverAtPort: portNrOrServiceName

create a new TCP server socket providing service.

 newUDP

create a UDP socket - no binding or other setup is done,
neither connect nor connect-wait is done.

usage example(s):

Socket newUDP

 newUDP: aServiceOrNil

create a UDP socket for a service -
neither connect nor connect-wait is done.

usage example(s):

Socket newUDP:4444. Socket newUDP:'activesync'.

 newUDPserverAtPort: aService

create a new UDP server socket providing service.

 newUNIX

create a UNIX domain socket - no binding or other setup is done,
neither connect nor connect-wait is done.
If the system does not support unix domain sockets (i.e. VMS or MSDOS),
return nil.

usage example(s):

Socket newUNIX

 newUNIXclientTo: pathName

create a new UNIX client socket connecting to a pathname.
Return a socket instance if ok, nil on failure.
Block until a connection is established (but only the current thread;
not the whole smalltalk).
If the system does not support unix domain sockets (i.e. VMS or MSDOS),
return nil.
See also: #newUNIXclientTo:withTimeout:

 newUNIXclientTo: pathName withTimeout: milliSecondsOrTimeDuration

create a new UNIX client socket connecting to a pathname.
Return a socket instance if ok, nil on failure.
If the millis arg is nonNil, stop trying to connect after that many milliseconds
and return nil.
If the system does not support unix domain sockets (i.e. VMS or MSDOS),
return nil.

usage example(s):

Socket newUNIXclientTo:'/tmp/foo' [ Socket newUNIXclientTo:'/tmp/foo' ] on:SocketErrorNotification do:[:ex| ex halt. ]

 newUNIXserverAt: pathName

create a new UNIX server socket providing service at a pathname.
If the system does not support unix domain sockets (i.e. VMS or MSDOS),
return nil.

 connectTo: service on: host

standard & easy client setup:
create new client tcp socket, bind and connect;
return the socket.
The thread blocks (interruptable), until the connection is established.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 networkLongOrderIsMSB

return the well known fact, that network byte order is most significant byte first

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 networkShortOrderIsMSB

return the well known fact, that network byte order is most significant byte first

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 provide: aService

standard & easy server setup:
create a new TCP server socket providing a service.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 appletalkAddressOfHost: aHostName

return the APPLETALK address for a hostname as a byteArray,
where the network bytes come first (no matter what the local byteorder is)
followed by the node byte.
If the host is unknown, return nil.
This is the reverse operation to #hostWithAppletalkAddress:.
WARNING: untested code - I have no appletalk to test this.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 hostWithAppletalkAddress: addrByteArray

return the hostname for an APPLETALK address.
The address is supposed to be a byteArray consisting of 3 bytes,
the network bytes come first (no matter what the local byteorder is).
The last byte is the node number.
Nil is returned for an unknown host or if it's not an appletalk host.
This is is the reverse operation to #appletalkAddressOfHost:.
WARNING: untested code - I have no appletalk to test this.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 hostWithIpAddress: addrByteArray

return the hostname for an IP (internet-) address.
The address is supposed to be a byteArray consisting of 4 bytes,
the network bytes come first (no matter what the local byteorder is).
Nil is returned for an unknown host or if it's not an internet host.
This is the reverse operation to #ipAddressOfHost:.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 hostWithIpV6Address: addrByteArray

return the hostname for an IPv6 (internet-) address.
The address is supposed to be a byteArray consisting ??? bytes,
the network bytes come first (no matter what the local byteorder is).
Nil is returned for an unknown host or if it's not an internet host.
This is the reverse operation to #ipV6AddressOfHost:.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 ipAddressOfHost: aHostName

return the IP (internet-) number for a hostname as a byteArray,
where the network bytes come first (no matter what the cpus byteOrder is).
If the host is unknown, return nil.
This is the reverse operation to #hostWithIpAddress:.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 ipV6AddressOfHost: aHostName

return the IPv6 (internet-) number for a hostname as a byteArray,
where the network bytes come first (no matter what the cpus byteOrder is).
If the host is unknown, return nil.
This is the reverse operation to #hostWithIpV6Address:.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 peerFromDomain: domain name: peerName port: port

 peerNameFromDomain: domain peer: peer

 portOfService: aNameOrNumber

returns the port-number for a given IP-service
or nil if no such service exists;
- used to convert service names to portNumbers

usage example(s):

Socket portOfService:'finger' Socket portOfService:'nntp' Socket portOfService:'echo' Socket portOfService:'snmp'

 portOfService: aNameOrNumber protocol: aProtocol

returns the port-number for a given IP-service
or nil if no such service exists;
- used to convert service names to portNumbers

usage example(s):

Socket portOfService:'echo' protocol:'udp' Socket portOfService:'echo' protocol:'tcp'

 protocolOfService: aNameOrNumber

returns the protocol (as string) for a given IP-service
or nil if no such service exists.

usage example(s):

Socket protocolOfService:'finger' Socket protocolOfService:'nntp' Socket protocolOfService:'xxx' Socket protocolOfService:79 Socket protocolOfService:'snmp'

 socketAddressClassForDomain: domain

self socketAddressClassForDomain:#AF_INET
self socketAddressClassForDomain:#AF_UNIX

 supportedProtocolFamilies

return a collection of supported protocol families.
This list specifies what the Socket class supports -
socket creation may still fail, if your system was built
without it.

usage example(s):

Socket supportedProtocolFamilies

 typeOfProtocol: aProtocol

given a protocols name (i.e. tcp, udp etc) return the connection type.
This method needs more ... - or is there a way to get this from the system ?

usage example(s):

Socket typeOfProtocol:'tcp' Socket typeOfProtocol:'ucp' Socket typeOfProtocol:(Socket protocolOfService:'nntp') Socket typeOfProtocol:(Socket protocolOfService:'echo')

Instance protocol:

 setReceiveTimeout: milliseconds

 setSendTimeout: milliseconds

 acceptNonBlock

 ioConnection

 notReadySignal

ST-80 mimicry.
for now - this is not yet raised

 readAppendStream

ST-80 mimicry.
In ST-80, socket is not a stream, but refers to one.
ST-80 code therefore uses 'Socket readWriteStream' to access
the actual stream.
In ST/X, sockets inherit from stream, so
this method returns the receiver, for transparency

 readStream

ST-80 mimicry.
In ST-80, socket is not a stream, but refers to one.
ST-80 code therefore uses 'Socket readStream' to access
the actual stream.
In ST/X, sockets inherit from stream, so
this method returns the receiver, for transparency

 writeStream

ST-80 mimicry.
In ST-80, socket is not a stream, but refers to one.
ST-80 code therefore uses 'Socket writeStream' to access
the actual stream.
In ST/X, sockets inherit from stream, so
this method returns the receiver, for transparency

 address

 bindTo: interfaceAddr port: portNr
( an extension from the stx:libcompat package )

 connectToHostNamed: hostName port: portNr

 dataAvailable

 destroy

 listenOn: aPortNr

 listenOn: aPortNr backlogSize: aNumber

 localAddress
( an extension from the stx:libcompat package )

^ self address

 noTimeout

disable timeouts - dummy for now

 peerName

return my peer (i.e. ipAddr + port);
May return nil if not yet setup completely.

 primSocketLocalPort: aSocket
( an extension from the stx:libcompat package )

 receiveUDPDataInto: aDataBuffer
( an extension from the stx:libcompat package )

squeak returns the result in a vector

 sendData: aStringOrByteArray

Send all of the data in the given array, even if it requires multiple calls to send it all.
Return the number of bytes sent.

 sendUDPData: bytes toHost: aHostAddr port: portNr
( an extension from the stx:libcompat package )

 setOption: optionName value: optionValue
( an extension from the stx:libcompat package )

Not all OperatingSystems offer this functionality for any option
(returns false, if unsupported)

 socketHandle
( an extension from the stx:libcompat package )

 waitForConnectionUntil: aTimestamp

return true if connected

 waitForData
( an extension from the stx:libcompat package )

 waitForDataForMsecs: timeout ifClosed: closedBlock ifTimedOut: timedOutBlock
( an extension from the stx:libcompat package )

Seconds resolution is way too much for for instance, UDP sockets running on local network, use this when timeouts > 1 sec is desirable

 waitForDataIfClosed: aBlock
( an extension from the stx:libcompat package )

 accept

create a new TCP socket from accepting on the receiver.
This method will suspend the current process if no connection is waiting.
For ST-80 compatibility

 blockingAccept

create a new TCP socket from accepting on the receiver.
This method will suspend the smalltalk image with all smalltalk processes if no connection is waiting.
For ST-80 compatibility

 bindAnonymously

bind to any address. A free port will be allocated.
Our own socket address will be determined after connection set up.
This is the default after the socket has been created

usage example(s):

self newTCP bindAnonymously; listenFor:1; yourself self newTCP bindAnonymously; port

 bindAnonymouslyToAddress: aSocketAddress

bind to address addressString.
A free port will be allocated

usage example(s):

self newTCP bindAnonymouslyToAddress:IPSocketAddress localHost; listenFor:1; yourself

 bindTo: aSocketAddress

ST80 compatible bind, expecting a socketAddress argument.
The socketAddress object (an instance of SocketAddress)
is supposed to respond to #portOrName and #address requests.

 bindTo: portNrOrNameString address: addressString

Old interface: bind the socket to an address
- returns true if ok, false otherwise.
Notify with a SocketErrorNotification on error.

The interpretation of hostOrPathNameOrSocketAddrOrNil portNrOrName depends on the domain:
Best use a SocketAddress
For backward compatibility:
AF_INET domain can also use (4byte) byteArray like internet numbers,
AF_UNIX domain cab use pathname strings.

 bindTo: portNrOrNameOrNil address: hostOrPathNameOrSocketAddrOrNil reuseAddress: reuse

Old interface: bind the socket to an address
Notify with a SocketErrorNotification on error.
- returns true if ok, false otherwise.

The interpretation of hostOrPathNameOrSocketAddrOrNil portNrOrName depends on the domain:
Best use a SocketAddress
For backward compatibility:
AF_INET domain can also use (4byte) byteArray like internet numbers,
AF_UNIX domain can use pathname strings.

The reuse boolean argument controls if the SO_REUSEADDR socket option
is to be set (to avoid the 'bind: address in use' error).

usage example(s):

(Socket domain:#'AF_INET' type:#stream) bindTo:2144 address:nil; yourself

 bindTo: aSocketAddress reuseAddress: reuse

Bind the socket to aSocketAddress - returns true if ok, false otherwise.
Notify with a SocketErrorNotification on error.

The reuse boolean argument controls if the SO_REUSEADDR socket option
is to be set (to avoid the 'bind: address in use' error).

You can bind to nil to bind to anyHost and assign a random port.

usage example(s):

(Socket domain:#'AF_INET' type:#stream) bindTo:(IPSocketAddress anyHost port:445) reuseAddress:false; yourself. (Socket domain:#'AF_INET' type:#stream) bindTo:139 reuseAddress:false; yourself. (Socket domain:#'AF_INET6' type:#stream) bindTo:nil reuseAddress:false; yourself. (Socket domain:#'AF_INET' type:#stream) bindTo:(IPSocketAddress localHost port:2122) reuseAddress:false; yourself. (Socket domain:#'AF_UNIX' type:#stream) bindTo:nil reuseAddress:false; yourself.

 listenFor: aNumber

start listening; return true if ok, false on error.
Notify with a SocketErrorNotification on error.
aNumber is the number of connect requests, that may be queued on the socket

usage example(s):

[ |sock| sock := Socket newTCP. sock listenFor:1. sock ] on:SocketErrorNotification do:[:ex| ex halt. ].

 abortAndClose

immediately abort the connection:
discard buffered data and close the stream

 shutDown

shutDown (initiate a graceful close)
and close (free the filedescriptor) the socket.
The close will return immediately and buffered data will be sent in the
background, unless you set linger

 shutDownInput

shutDown the input side of the socket.
Any read on the socket will signal end-of-file from now on.
The other side MAY be informed, that no more data will be accepted
(e.g. setting the TCP-Windowsize to 0)

 shutDownOutput

shutDown the output side of the socket.
Any write to the socket will signal end-of-file from now on.
An orderly release (TCP FIN) will be initiated after the last buffered data
has been sent, so the other side will get a end-of-file condition eventually.
If you set linger > 0, the operation will wait until buffered data
has been delivered to the peer.
Otherwise the operation returns immediately.

 connectTo: aSocketAddress

 connectTo: hostOrPathName port: portNrOrName

Backward compatibility connect; connect to port, portNrOrNameOrNil on host, hostOrPathNameOrSocketAddr.
For backward compatibility, hostOrPathNameOrSocketAddr may be also a string or a byteArray,
but it is recommended to pass SocketAddress instances.

Return true if ok, false otherwise.
The current process will block (but not the whole Smalltalk) until the connection is established.
See also: #connectTo:port:withTimeout: for a somewhat nicer interface.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 connectTo: hostOrPathNameOrSocketAddr port: portNrOrNameOrNil withTimeout: milliSecondsOrTimeDuration

Backward compatibility connect; connect to port, portNrOrNameOrNil on host, hostOrPathNameOrSocketAddr.
For backward compatibility, hostOrPathNameOrSocketAddr may be also a string or a byteArray,
but it is recommended to pass SocketAddress instances.

Return true if ok, false otherwise.
Notify with a SocketErrorNotification on error.

The current process will block (but not the whole Smalltalk) until the connection is established,
or milliSecondsOrTimeDuration milliseconds have passed.

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 connectTo: aSocketAddress withTimeout: milliSecondsOrTimeDuration

Connect to a SocketAddress.

Return true if ok, false otherwise.
Notify with a SocketErrorNotification on error.

The current process will block (but not the whole Smalltalk) until the connection is established,
or timeout milliseconds have passed.

 receiveBuffer: aDataBuffer start: startIndex for: nBytes

receive data
Return the number of bytes received.
The thread blocks until data arrives - you may want to wait before
receiving, using #readWait or #readWaitWithTimeout:.

 receiveFrom: aSocketAddress buffer: aDataBuffer

receive datagramm data - put address of originating host into
aSocketAddress, data into aDataBuffer.
aDataBuffer must be ByteArray-like.
For backward compatibility, aSocketAddress may be a non-SocketAddress;
then, it must be a byteArray with appropriate size for the addressBytes.

Return the number of bytes received.
The thread blocks until data arrives - you may want to wait before
receiving, using #readWait or #readWaitWithTimeout:.

 receiveFrom: aSocketAddress buffer: aDataBuffer start: startIndex for: nBytes

Modified (format): / 21-03-2018 / 19:32:27 / stefan

 receiveFrom: aSocketAddress buffer: aDataBuffer start: startIndex for: nBytes flags: flags

receive datagramm data
- put address of originating host into aSocketAddress, data into aDataBuffer.
aDataBuffer must be ByteArray-like.
For backward compatibility, aSocketAddress may be a non-SocketAddress;
then, it must be a byteArray with appropriate size for the addressBytes.

Return the number of bytes received.
The thread blocks until data arrives - you may want to wait before
receiving, using #readWait or #readWaitWithTimeout:.

 sendBuffer: aDataBuffer start: startIndex for: nBytes flags: flags

send data. aDataBuffer be ByteArray-like.
Return the number of bytes transmitted, or a negative number on error.

 sendTo: aSocketAddress buffer: buffer

send datagramm data - fetch address of destination host from
aSocketAddress, data from aDataBuffer.
aDataBuffer must be ByteArray-like.
aSocketAddress must be a valid SocketAddress for my domain
(i.e. for IPv4, an IPSocketAddress).
For backward compatibility, a ByteArray is still supported in aSocketAddress
(i.e. for IPv4, a 4-byte byteArray).
Return the number of bytes transmitted.

 sendTo: aSocketAddress buffer: buffer start: startIndex for: count

send datagramm data - fetch address of destination host from
aSocketAddress, data from aDataBuffer.
aDataBuffer must be ByteArray-like.
aSocketAddress must be a valid SocketAddress for my domain
(i.e. for IPv4, an IPSocketAddress).
For backward compatibility, a ByteArray is still supported in aSocketAddress
(i.e. for IPv4, a 4-byte byteArray).
Return the number of bytes transmitted.

 sendTo: aSocketAddress buffer: aDataBuffer start: startIndex for: nBytes flags: flags

send datagramm data - fetch address of destination host from
aSocketAddress, data from aDataBuffer starting at startIndex,
sending count bytes.
aDataBuffer must be ByteArray-like.
aSocketAddress must be a valid SocketAddress for my domain
(i.e. for IPv4, an IPSocketAddress).
For backward compatibility, a ByteArray is still supported in aSocketAddress
(i.e. for IPv4, a 4-byte byteArray).
Return the number of bytes transmitted.

 reportError: osErrorNumber

report an error to the initiator of a Socket operation.
We raise a notification for newer code, and also
return false for old code not catching the notification.

 finalize

do an abortive release - discard buffered data

 initialize

transparent

 getSocketAdress

BAD SPELLING, of #getSocketAddress, kept for compatibility with swazoo

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 getSocketError

get the SO_ERROR form the socket, which indicates the
result of an asynchronous operation

 listenWithBacklog: aNumber

same as listenFor: - backward compatibility with old ST/X

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 primAcceptOn: aServerSocket blocking: blocking

accept a connection on a server port (created with:'Socket>>newTCP:')
usage is: (Socket basicNew acceptOn:(Socket newTCP:9999)).
Return the true if ok; false if not.
Notify with a SocketErrorNotification on error.

If blocking is true, the accept() syscall (and the whole smalltalk image)
will block, until a connection is accepted.
If blocking is false, this call will return immediately, if there is no connection pending.

 setSocketOption: option argument: arg1 argument: arg2

 shutdown: howNum

shutDown the socket - inform it that no more I/O will be performed.
0 - read side (no further reads)
the tcp receive window is closed, so the peer cannot send more data.
1 - write side (no further writes)
first, all queued data will be delivered to the peer.
Then, an orderly release (TCP FIN) is sent to signal the peer,
that we will not send more data.
2 - both read side and write side.

 printOn: aStream

(comment from inherited method)
append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

 domain

return the sockets addressing domain (i.e. #AF_INET, #AF_INET6, #AF_UNIX, ...)

 getFullPeerAddress

implemented for swazoo project (primitive code can't be loaded as extension)
Answer my own address (I am bound to this address).
Note that this address may change after a connect or accept.

 getFullSocketAddress

implemented for swazoo project (primitive code can't be loaded as extension)
Answer my own address (I am bound to this address).
Note that this address may change after a connect or accept.

 getName

return the name; here, we return the ports name

 getPeer

ST-80 compatibility: return an IPSocketAddress instance representing
my hostname/port combination.
If you are interested in the hostname, use getPeerName directly.

 getPeerName

return the peer name; that's the hostname (or dotted name) of the
partners host after an accept.

 getSocketAddress

implemented for swazoo project primitive code cant load as extension
answer my own address (I am bound to this address).
Note that this address may change after connect or accept.

 isActive

return true, if the receiver has a connection or is bound or listening

 isConnected

return true, if the receiver has a connection

 port

return the port number (or name for unix-sockets) to which the socket is bound
- so this is the local port.

usage example(s):

port := self getFullSocketAddress port.

 socketAddressClass

get the matching SocketAddress class for this socket

 type

return the sockets connection type (i.e. #datagram, #stream etc)

 domain: domainArg type: typeArg

set up socket with domain and type.
This is a low level entry; no binding, listening or connect
is done. Both arguments must be symbols from one of
#AF_INET, #AF_INET6, #AF_UNIX ... and #stream, #datagram, #raw resp.

 domain: domainArg type: typeArg protocol: protocolNumber

set up socket with domain, type and protocol number.
This is a low level entry; no binding, listening or connect
is done. Both arguments must be symbols from one of
#AF_INET, #AF_INET6, #AF_UNIX ... and #stream, #datagram, #raw resp.

usage example(s):

Socket new domain:#AF_INET type:#stream Socket new domain:#AF_UNIX type:#stream

 linger: anIntegerOrNil

set the linger behavior on close:
anIntegerOrNil == nil: close returns immediately, socket tries
to send buffered data in background.
anIntegerOrNil == 0: close returns immediately, bufferd data is discarded.
anIntegerOrNil > 0: close waits this many seconds for buffered data
to be delivered, after this time buffered data is
discarded and close returns with an error.
(returns false, if unsupported)

 receiveBufferSize

get the send buffer size - for special applications only.
Not all operatingSystems offer this functionality
(returns nil, if unsupported)

 receiveBufferSize: size

set the receive buffer size - for special applications only.
Not all operatingSystems offer this functionality
(returns false, if unsupported)

 receiveTimeout

get the receive timeout in millis - for special applications only.
Not all operatingSystems offer this functionality
(returns nil, if unsupported)

usage example(s):

Socket newTCP receiveTimeout

 receiveTimeout: secondsOrTimeDuration

set the receive timeout - for special applications only.
Not all operatingSystems offer this functionality
(returns false, if unsupported).

From linux manpage:
SO_RCVTIMEO and SO_SNDTIMEO
Specify the receiving or sending timeouts until reporting an error. The argument is a
struct timeval. If an input or output function blocks for this period of time, and data has
been sent or received, the return value of that function will be the amount of data trans-
ferred; if no data has been transferred and the timeout has been reached, then -1 is
returned with errno set to EAGAIN or EWOULDBLOCK, or EINPROGRESS (for connect(2)) just as if
the socket was specified to be nonblocking. If the timeout is set to zero (the default),
then the operation will never timeout. Timeouts only have effect for system calls that per-
form socket I/O (e.g., read(2), recvmsg(2), send(2), sendmsg(2)); timeouts have no effect
for select(2), poll(2), epoll_wait(2), and so on.

usage example(s):

Socket newTCP receiveTimeout:5s; receiveTimeout

 sendBufferSize

get the send buffer size - for special applications only.
Not all operatingSystems offer this functionality
(returns nil, if unsupported)

 sendBufferSize: size

set the send buffer size - for special applications only.
Not all operatingSystems offer this functionality
(returns false, if unsupported)

 sendTimeout

get the send timeout in millis - for special applications only.
Not all operatingSystems offer this functionality
(returns nil, if unsupported)

usage example(s):

Socket newTCP sendTimeout

 sendTimeout: secondsOrTimeDuration

set the send timeout - for special applications only.
Not all operatingSystems offer this functionality
(returns false, if unsupported).
From linux manpage:
SO_RCVTIMEO and SO_SNDTIMEO
Specify the receiving or sending timeouts until reporting an error. The argument is a
struct timeval. If an input or output function blocks for this period of time, and data has
been sent or received, the return value of that function will be the amount of data trans-
ferred; if no data has been transferred and the timeout has been reached, then -1 is
returned with errno set to EAGAIN or EWOULDBLOCK, or EINPROGRESS (for connect(2)) just as if
the socket was specified to be nonblocking. If the timeout is set to zero (the default),
then the operation will never timeout. Timeouts only have effect for system calls that per-
form socket I/O (e.g., read(2), recvmsg(2), send(2), sendmsg(2)); timeouts have no effect
for select(2), poll(2), epoll_wait(2), and so on.

usage example(s):

Socket newTCP sendTimeout:5s; sendTimeout

 setTCPCork: aBoolean

enable/disable TCP_CORK (do-not-send-partial-frames)
For special applications only.
Not all OperatingSystems offer this functionality
(returns false, if unsupported)

 setTCPNoDelay: aBoolean

enable/disable TCP_NODELAY (i.e. disable/enable the Nagle algorithm)
For special applications only.
Not all OperatingSystems offer this functionality
(returns false, if unsupported)

 waitForNewConnectionOrDataOnAny: otherConnections timeout: secondsOrTimeDurationOrNil

suspend the current process, until either a new connection comes
in at the receiver, or data arrives on any of the otherConnections.
For a new connection, an accept is performed and the new socket is returned.
For an old connection, that socket is returned.
In any case, the caller gets a socket to operate on as return value,
or nil, if a timeout occurred.
This method implements the inner wait-primitive of a multi-connection
server application.

 waitForNewConnectionWithTimeout: secondsOrTimeDurationOrNil

suspend the current process, until a new connection comes
in at the receiver or a timeout occurs.
For a new connection, an accept is performed and the new socket is returned.
Returns nil, if a timeout occurred.
This method implements the inner wait-primitive of a single-connection
server application.

Examples:

    |sock|

    sock := Socket newTCPclientToHost:'smtp.exept.de' port:'smtp'.
    sock isNil ifTrue:[
        self warn:'no smtp daemon is running'.
        ^ self
    ].
    Transcript showCR:sock nextLine.

    sock nextPutAll:'HELO STX socket test'; cr.
    Transcript showCR:sock nextLine.
    sock close

    |sock entry|

    sock := Socket newTCPclientToHost:'localhost' port:'finger'.
    sock isNil ifTrue:[
        self warn:'no finger daemon is running'.
        ^ self
    ].
    sock useCRLF:true.
    sock buffered:false.
    sock isNil ifTrue:[
        Transcript showCR:'cannot connect to local finger daemon'
    ] ifFalse:[
        sock nextPutAll:(OperatingSystem getLoginName).
        sock cr.

        entry := sock nextLine.
        Transcript showCR:entry.

        sock close
    ]

    |sock|

    sock := Socket newTCPclientToHost:'www.exept.de' port:'ftp'.

    sock buffered:false.
    Transcript showCR:sock nextLine.
    sock nextPutAll:('USER ' , 'anonymous'); cr.
    Transcript showCR:sock nextLine.
    sock nextPutAll:('PASS ' , 'fooBar'); cr.
    Transcript showCR:sock nextLine.
    sock nextPutAll:'HELP'; cr.
    [
        |line|
        line := sock nextLine.
        Transcript showCR:line.
        (line at:4) = $-
    ] whileTrue.
    sock close.

    'don't know enough of the ftp protocol to continue here ...'

    |sock port|

    sock := Socket newUDP.
    port := Socket portOfService:'snmp'.
    sock connectTo:'224.1.2.3' port:port.
    sock buffered:false.
    Transcript showCR:'got it'.
    sock close.

    |connectSock sock|

    connectSock := Socket newTCPserverAtPort:9998.
    connectSock isNil ifTrue:[
        Transcript showCR:'socket setup failed.'.
    ] ifFalse:[
        Transcript showCR:'listen ..'.
        (connectSock listenFor:5) ifFalse:[
            Transcript showCR:'listen failed.'.
        ] ifTrue:[
            Transcript showCR:'wait'.
            connectSock readWait.
            Transcript showCR:'accept'.
            sock := connectSock accept.
            sock isNil ifTrue:[
                Transcript showCR:'accept failed.'.
            ] ifFalse:[
                sock buffered:false.
                Transcript showCR:'server: got it'.
                'can now do transfer via sock'.
                Transcript showCR:'read'.
                Transcript showCR:('got: ' , sock nextLine).

                Transcript showCR:'close'.
                sock close
            ].
            connectSock close.
        ]
    ]

    |sock|

    sock := Socket newTCPclientToHost:'localhost' port:9998.
    sock isNil ifTrue:[
        Transcript showCR:'nope'
    ] ifFalse:[
        sock buffered:false.
        Transcript showCR:'client: got it'.
        'can now do transfer via sock'.
        Transcript showCR:'sending <hello>'.
        sock nextPutLine:'hello'.
        sock close
    ]

    |sock|

    sock := Socket newUNIXclientTo:'/tmp/ud_socket'.
    sock isNil ifTrue:[
        Transcript showCR:'nope'
    ] ifFalse:[
        sock buffered:false.
        Transcript showCR:'client: got it'.
        'can now do transfer via sock'.
        Transcript showCR:'sending <hello>'.
        sock nextPutLine:'hello'.
        sock close
    ]

    |udpSock sock addr n dataBuffer|

    udpSock := Socket newUDPserverAtPort:9999.
    udpSock isNil ifTrue:[
        Transcript showCR:'socket setup failed.'.
    ] ifFalse:[
        Transcript showCR:'wait'.
        udpSock readWait.

        addr := IPSocketAddress new.
        dataBuffer := ByteArray new:1000.
        n := udpSock receiveFrom:addr buffer:dataBuffer start:1 for:dataBuffer size.
        n > 0 ifTrue:[
            Transcript showCR:('got: ' , n printString , 'bytes  from ' , addr printString).
            Transcript showCR:('data: ' , (dataBuffer copyTo:n) printString).
        ] ifFalse:[
            Transcript showCR:'read failed'.
        ].

        Transcript showCR:'close'.
        udpSock close
    ]

    |sock|

    sock := Socket newUDP.
    sock isNil ifTrue:[
        Transcript showCR:'nope'
    ] ifFalse:[
        sock
            sendTo:(IPSocketAddress hostName:'127.0.0.1' port:9999) buffer:'hello world'.
        sock close
    ]

    |udpSock sock addr n dataBuffer|

    udpSock := Socket newUDPserverAtPort:9999.
    udpSock isNil ifTrue:[
        Transcript showCR:'socket setup failed.'.
    ] ifFalse:[
        udpSock setSocketOption:#'IP_ADD_MEMBERSHIP' argument:#[224 1 2 3] argument:#[0 0 0 0].
        Transcript showCR:'wait'.
        udpSock readWait.

        addr := IPSocketAddress new.
        dataBuffer := ByteArray new:1000.
        n := udpSock receiveFrom:addr buffer:dataBuffer start:1 for:dataBuffer size.
        n > 0 ifTrue:[
            Transcript showCR:('got: ' , n printString , 'bytes  from ' , addr printString).
            Transcript showCR:('data: ' , (dataBuffer copyTo:n) printString).
        ] ifFalse:[
            Transcript showCR:'read failed'.
        ].

        Transcript showCR:'close'.
        udpSock close
    ]

    |sock|

    sock := Socket newUDP.
    sock isNil ifTrue:[
        Transcript showCR:'nope'
    ] ifFalse:[
        sock
            setSocketOption:#'IP_MULTICAST_TTL' argument:3 argument:nil;
            sendTo:(IPSocketAddress hostName:'224.1.2.3' port:9999) buffer:'hello world'.
        sock close
    ]

    |myAddress list top hosts walkProcess port|

    myAddress := OperatingSystem getNetworkAddresses
                    keysAndValuesSelect:[:eachIFName :eachAddress|
                        eachAddress isLocal not
                        and:[eachIFName = 'wlan0']
                    ].
    myAddress := myAddress first hostAddress.

    port := Socket portOfService:'echo'.
    port isNil ifTrue:[
        self error:'dont know echo port'.
        ^ self
    ].

    top := StandardSystemView new.
    top label:'PING net walk'.

    list := ScrollableView for:ListView in:top.
    list origin:0.0@0.0 corner:1.0@1.0.

    top openAndWait.

    walkProcess := [
        |l low hi direction tryHostID dottedName hostName conn addr|

        l := SortedCollection new.

        ' only works with type C-net
          the code below could simply do 1 to:254 do:[:hostID }
          but, to probe likely hosts earlier, the probing is done
          ping-pong like around my ip-address (assuming, that other machines
          have numbers around my own)'.

        low := hi := (myAddress at:4).
        direction := 1.

        [low > 0 or:[hi < 255]] whileTrue:[
            direction > 0 ifTrue:[
                hi := hi + 1.
                tryHostID := hi.
                direction := -1.
            ] ifFalse:[
                low := low - 1.
                tryHostID := low.
                direction := 1.
            ].
            (tryHostID between:1 and:254) ifTrue:[
                dottedName := (myAddress at:1) printString
                              , '.' , (myAddress at:2) printString
                              , '.' , (myAddress at:3) printString
                              , '.' , tryHostID printString.

                top label:'PING net walk - trying ' , dottedName.

                top windowGroup withCursor:Cursor wait do:[
                    conn := Socket newTCPclientToHost:dottedName port:port withTimeout:1000.
                    conn notNil ifTrue:[
                        addr := Socket ipAddressOfHost:dottedName.
                        hostName := Socket hostWithIpAddress:addr.
                        hostName isNil ifTrue:[
                            hostName :='?'
                        ].
                        l add:(dottedName paddedTo:15 with:Character space)
                               , ' '
                               , (hostName paddedTo:15 with:Character space)
                               , ' up & reachable'.
                        list list:l.
                        conn close.
                    ]
                ].
            ].
        ].
        top label:'PING reachable hosts'.
    ] forkAt:(Processor userBackgroundPriority).
    walkProcess name:'ping net walker'.

    | socket address buffer msgSize clients |
    clients := Set new.
    address := IPSocketAddress new.
    buffer := String new: 1024.

    socket := self newUDPserverAtPort: 6666.

    Transcript showCR: 'server starting'.

    [
        [true] whileTrue: [
            (socket readWaitWithTimeoutMs: 200) ifFalse: [
                msgSize := socket
                        receiveFrom: address
                        buffer: buffer
                        start: 1
                        for: buffer size.

                clients add: address copy.
                clients do: [ :clientAddress |
                        socket
                                sendTo: clientAddress
                                buffer: buffer
                                start: 1
                                for: msgSize]]
        ]
    ] ensure:[
        Transcript showCR: 'server shutting down'.
        socket close
    ]

    | socket address buffer host msg |

    host := Dialog
            request: 'What is the name of the server''s host?'
            initialAnswer: 'localhost'.

    socket := self newUDP.

    address := IPSocketAddress hostName: host port: 6666.

    buffer := ByteArray new: 1000.
    [
        [(msg := Dialog request: 'Say something') isEmpty] whileFalse:[
            | replySize stream |

            socket writeWait.
            stream := buffer writeStream.
            stream nextPutAll: msg.
            socket sendTo:address buffer:buffer start:1 for:stream position.
            socket readWait.

            replySize := socket receiveFrom:address buffer:buffer.
            replySize > 0 ifTrue: [
                Transcript cr; nextPutAll: 'Server acknowledged: '.
                Transcript show: ((buffer copyFrom: 1 to: replySize) asString)
            ]
        ]
    ] ensure: [socket close].
    Transcript cr

    |readerTask readingSocket writingSocket|

    readingSocket := self newTCPserverAtPort:9999.
    readerTask :=
        [
            |connection|

            readingSocket listenFor:1.
            connection := readingSocket accept.
            readingSocket close.
            [connection atEnd] whileFalse:[
                Transcript showCR:(connection nextLine).
            ].
            connection close.
        ] fork.

    Delay waitForSeconds:1.
    writingSocket := self newTCPclientToHost:'localhost' port:9999.
    writingSocket nextPutLine:'Hello'.
    writingSocket nextPutLine:'World'.
    writingSocket close.