cep -
Create a communications endpoint
package require ceptcl
cep ?options? ?host? ?port?
cep -server command ?options? port/name
cep -receiver command ?options? port
This command creates one or two communications endpoints (cep)s and returns one
or two channel identifiers that may be used in future invocations of commands like
read, puts and flush.
On Unix systems, ceps are usually implemented with sockets.
Supported domains are local (unix domain sockets and localpairs),
inet (IPV4) and inet6 (IPV6).
Supported types are stream (TCP), datagram (UDP) and raw.
The cep command may be used to open either the client or
server side of a connection, depending on whether the -server
switch is specified. A cep created with the -receiver option
can bypass the Tcl channel system and provide additional
information with received messages.
Note that the default encoding for all ceps except receceiver ceps is the system
encoding, as returned by encoding system. Most of the time, you
will need to use fconfigure to alter this to something else,
such as utf-8 (ideal for communicating with other Tcl
processes) or iso8859-1 (useful for many network protocols,
especially the older ones). Messages received on receiver ceps
do not pass through the Tcl channel system.
Ceps created in the local domain are either local
servers or clients, or localpairs.
Local ceps are used for communciations where
the communicating processes reside on the same machine.
All other ceps are considered to be non-local;
the communicating processes need not
reside on the same machine. A client cep created without
a port being specified is a local cep. A client cep created without
a host or a port being specified is specifically a localpair
and generally a local cep. The length of the name of a local
cep is determined by the host operating system. The -sockname
option to the fconfigure command may be used to determine
the final name of a local cep.
The host/port combination of \'{} -1\' (the nil address)
may be specified as the destination host and port
for connection or binding. When specified, the cep will not
attempt to connect or bind to the destination.
The nil address can also be used to disassociate from a peer.
If the -server or -receiver options are not specified, then a client
cep is created, and the command returns a channel identifier
that may be used for both reading and writing. If the nil address
is not specified, then a connection attempt will be made.
For non-local ceps, host and port specify a host
and port to connect to. For stream types (if not using the
nil address) there must be a server accepting connections
on this port. For datagram and raw types, the connect will always
succeed. Port is an integer port number (or service name, where supported and
understood by the host operating system) and host
is either a domain-style name such as www.tcl.tk or
a numerical IP address such as 127.0.0.1 (type inet) or an
IPV6 address such as FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 (type inet6).
Use localhost to refer to the host on which the command is invoked.
For local ceps, the host refers to a local communications endpoint
(usually a file on the local file system) and port is not specified.
The following options may also be present before host
to specify additional information about the connection:
- -myaddr addr
- Addr gives the domain-style name or numerical IP or IPV6 address of
the client-side network interface to use for the connection.
This option may be useful if the client machine has multiple network
interfaces. If the option is omitted then the client-side interface
will be chosen by the system software.
- -myport port
- Port specifies an integer port number (or service name, where
supported and understood by the host operating system) to use for the
client's side of the connection. If this option is omitted, the client's
port number will be chosen at random by the system software.
- -async
- For stream type ceps, the -async option will cause the client cep to be connected
asynchronously. This means that the cep will be created immediately but
may not yet be connected to the server, when the call to cep
returns. When a gets or flush is done on the cep before the
connection attempt succeeds or fails, if the cep is in blocking mode, the
operation will wait until the connection is completed or fails. If the
cep is in nonblocking mode and a gets or flush is done on
the cep before the connection attempt succeeds or fails, the operation
returns immediately and fblocked on the cep will return 1.
Datagram and raw ceps should work in a similar fashion,
although blocking may have little effect.
Using the async option with datagram or raw ceps
doesn't make a lot of sense; a connection attempt will always succeed.
This has received little testing.
If the -server option is specified then the new cep
will be a server cep.
Tcl will automatically accept connections to the newly created cep.
For each connection Tcl will create a new channel that may be used to
communicate with the client.
Server channels cannot be used for input or output; their sole use is to
accept new client connections. The channels created for each incoming
client connection are opened for input and output. Closing the server
channel shuts down the server so that no new connections will be
accepted; however, existing connections will be unaffected.
Server ceps depend on the Tcl event mechanism to find out when
new connections are opened. If the application doesn't enter the
event loop, for example by invoking the vwait command or
calling the C procedure Tcl_DoOneEvent, then no connections
will be accepted.
If domain is local then the new cep will
be a server for the local communications endpoint (usually a file
on the local filesystem) named by port/name.
Tcl will automatically accept connections to the cep.
For each connection Tcl will create a new channel that may be used to
communicate with the client. Tcl then invokes command
with three additional arguments: the name of the new channel, the
name of the cep as given by port/name, and a two element
list containing the euid and egid (in that order) of the client.
If domain is inet or inet6 then the new cep will be
a be a server for the port given by por/name (either an integer
or a service name, where supported and understood by the host
operating system).
Tcl will automatically accept connections to the given port.
For each connection Tcl will create a new channel that may be used to
communicate with the client. Tcl then invokes command
with three additional arguments: the name of the new channel, the
address, in network address notation, of the client's host, and
the client's port number.
The following additional option may also be specified before host:
- -myaddr addr
- Addr gives the domain-style name or numerical IP or IPV6 address of
the server-side network interface to use for the connection.
This option may be useful if the server machine has multiple network
interfaces. If the option is omitted then the server cep is bound
to the special address INADDR_ANY or :: so that it can accept
connections from any interface.
If port is specified as zero, the operating system will allocate
an unused port for use as a server cep. The port number actually
allocated my be retrieved from the created server cep using the
fconfigure command to retrieve the -sockname option as
described below.
If the -receiver option is specified, a receiver cep will
be created.
Receivers are datagram or raw ceps which receive messages
and pass them unmodifed, with sender information, When a message is
received on the cep, Tcl will invoke command with five
additional arguments: the name of the channel, the
address, in network address notation, of the client's host,
the client's port number, the length of the message, and
the received message.
Localpairs are two client ceps connected back-to-back.
The cep command will return a list of two ceps, if sucessfull.
The domain for localpair ceps is local by default,
any other domain will probably generate an error.
The options -type and -protocol may also be specified, though
they may be of limited use.
These options are common to all invocations of the cep command.
- -domain domain
- Domain specifices the domain or 'address family' of the cep.
Valid domains are local, inet and inet6.
If the domain is not specified, then a default domain is selected.
The default will be inet for non-local ceps and local
for local ceps (port is not specifed)
and localpairs (host and port are not specified).
- -type type
- Type specifies the type of the cep.
Valid types are stream, datagram and raw.
If the type is not specified, then a default type is selected.
The default will be stream for all ceps.
- -protocol protocol
- Protocol specifies the protocol of the cep.
This may be an integer protocol number or a protocol name, where
supported and understood by the host operating system.
The default is 0.
These options are common only to invocations of the cep command
where a cep with a non-local domain is being created.
- -noresolve
- If the -noresolve option is specified, then name resolution
will be disabled for the new cep. Name resolution may sometimes
cause unwanted delays in communications applications. Name
resolution is enabled by default.
- -noreuseaddr
- If the -noreuseaddr option is specified, then an attempt to
bind or start a server on an address for which a cep (or
other socket) is bound or a server is running will fail
due to address conflict.
Address reuse is enabled by default.
- -reuseport
- If the -reuseport option is specified, then an attempt to
bind or start a server on a port for which a cep (or
other socket) is bound or a server is running will not
fail due to port conflict.
Port reuse is disabled by default.
The fconfigure command may be used to set or
retrieve several configuration options for cep channels.
- -domain
- This option returns the domain of the given cep, one of: local, inet or inet6.
- -error
- This option gets the current error status of the given cep. This
is useful when you need to determine if an asynchronous connect
operation succeeded. If there was an error, the error message is
returned. If there was no error, an empty string is returned.
- -peereid
- This will return a two element list containing the effective user
and group ids of a locally connected peer.
If the given cep is a non-local cep, the two element list {-1 -1} will be returned.
- -protocol
- This option returns the protocol name of the given cep. If the protocol number is 0,
the string "default" will be returned.
- -sockname
- This option returns a list of three elements, the address, the host name
and the port number for the given cep.
If name resolution has been disabled for the given cep, no attempt will be
made to resolve the host name from the address, the second element of
the list is identical to the address, its first element.
If name resolution has been enabled for the given cep, an attempt will be
made to resolve the host name from the address.
If the host name cannot be resolved, the second element of
the list is identical to the address, its first element.
- -type
- This option returns the type of the given cep, one of: stream, datagram or raw.
- -join group
- This option will attempt to join the multicast group group.
An empty string passed to this option will do nothing, and
will not generate an error.
- -leave group
- This option will attempt to leave the multicast group group.
An empty string passed to this option will do nothing, and
will not generate an error.
- -broadcast boolean
- This otion sets or returns the broadcast flag for the cep. This may
be required on some systems in order to send brodcast messages.
This option is only useful for datagram and raw ceps; the system
may consider it an error to attempt to set this for other cep types.
- -header boolean
- This option only applies to raw inet ceps. If true, then the system
will expect the user to supply the ip header for outgoing messages.
The ip header is always received.
- -hops integer
- This option sets or returns the number of unicast hops (ttl or time-to-live) for outgoing messages.
For stream and datagram ceps.
- -loop boolean
- This option sets or returns the multicast loopback option for the cep.
If true then outbound multicast messages will be looped back to the sender.
- -maddr addr
- This option will set or returns the interface address
for outbound multicast messages. It should be possible to set
it to INADDR_ANY (to reset to default), but that's not
implemented yet.
- -mhops integer
- This option sets or returns the number of multicast hops (ttl or time-to-live) for outgoing messages.
- -peername host port
- When queried, this option returns a list of three elements; these are the
address, the host name and the port of the peer to which the
given cep is connected or bound.
If name resolution has been disabled for the given cep, no attempt will be
made to resolve the host name from the address, the second element of
the list is identical to the address, its first element.
If name resolution has been enabled for the given cep, an attempt will be
made to resolve the host name from the address.
If the host name cannot be resolved, the second element of
the list is identical to the address, its first element.
For datagram and raw ceps this option may be used
to rebind the cep to a new host to which all outbound messages
will be sent. Inbound messages will be received only from this host.
Only one peer may be associated at a time. Setting a new peer will
dissaociate from the current peer, if any. If the nil address
is specified, then the cep will drop any association it may have.
A cep without an association can receive messages from any host.
- -resolve boolean
- This option sets or returns the resolve option for the given cep.
If true then the system will attempt to resolve between host names and addresses
when options -sockname or -peername are used, when joining or
leaving a multicast group, or when a server cep accepts a new client.
- -route boolean
- This option only applies to ceps of domain inet
and types stream or datagram.
If set to true, then the system will route outgoing messages for the given cep.
When querying, a boolean value is returned; true indicates
that the system will route outgoing messages for the given cep.
- -shutdown value(s)
- This option returns the shutdown state of the given cep,
or shuts down the cep for reading, writing or both.
Valid values are read, write, {read write}, or {write read}.
fconfigure(n), flush(n), open(n), read(n), sendto(n), socket(n)
icmp(4), ip(4), ip6(4), socket(2), tcp(4), udp(4), etc, and a bunch of RFCs.
bind, channel, connection, domain name, host, network address, socket, tcp, udp