mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
Start of the sockets documentation make-over
Describe in detail all possible options to socket_create() without the need to refer to other documentation. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@106231 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Jason Greene
parent
ad0b4e7089
commit
4d84a12305
1 changed files with 141 additions and 33 deletions
|
|
@ -1,5 +1,5 @@
|
|||
<?xml version="1.0" encoding="iso-8859-1"?>
|
||||
<!-- $Revision: 1.3 $ -->
|
||||
<!-- $Revision: 1.4 $ -->
|
||||
<!-- splitted from ./en/functions/sockets.xml, last change in rev 1.4 -->
|
||||
<refentry id="function.socket-create">
|
||||
<refnamediv>
|
||||
|
|
@ -14,47 +14,155 @@
|
|||
<methodparam><type>int</type><parameter>type</parameter></methodparam>
|
||||
<methodparam><type>int</type><parameter>protocol</parameter></methodparam>
|
||||
</methodsynopsis>
|
||||
&warn.experimental.func;
|
||||
<para>
|
||||
Creates a communication endpoint (a socket), and returns a socket
|
||||
resource.
|
||||
Creates and returns a socket resource, also referred to as an endpoint
|
||||
of communication. A typical network connection is made up of 2 sockets, one
|
||||
performing the role of the client, and another performing the role of the server.
|
||||
</para>
|
||||
<para>
|
||||
The <parameter>domain</parameter> parameter sets the domain (protocol
|
||||
family) to be used for communication. Currently,
|
||||
<constant>AF_INET</constant> and <constant>AF_UNIX</constant> are
|
||||
understood. <constant>AF_INET</constant> is typical used for internet
|
||||
based communication. <constant>AF_UNIX</constant> uses pathnames to
|
||||
identify sockets and can therefore only be used for local communication
|
||||
(which is faster, on the other hand).
|
||||
The <parameter>domain</parameter> parameter specifies the protocol
|
||||
family to be used by the socket.
|
||||
</para>
|
||||
<table>
|
||||
<title>Available address/protocol families</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Domain</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>AF_INET</entry>
|
||||
<entry>
|
||||
IPv4 Internet based protocols. TCP and UDP are common protocols of
|
||||
this protocol family.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>AF_UNIX</entry>
|
||||
<entry>
|
||||
Local communication protocol family. High efficiency and low
|
||||
overhead make it a great form of IPC (Interprocess Communication).
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
<para>
|
||||
The <parameter>type</parameter> parameter selects the socket
|
||||
type. This is one of <constant>SOCK_STREAM</constant>,
|
||||
<constant>SOCK_DGRAM</constant>,
|
||||
<constant>SOCK_SEQPACKET</constant>,
|
||||
<constant>SOCK_RAW</constant>, <constant>SOCK_RDM</constant>, or
|
||||
<constant>SOCK_PACKET</constant>. The two most common types are
|
||||
<constant>SOCK_DGRAM</constant> for <literal>UDP</literal>
|
||||
(connectionless) communication
|
||||
and <constant>SOCK_STREAM</constant> for <literal>TCP</literal>
|
||||
communication.
|
||||
The <parameter>type</parameter> parameter selects the type of communication
|
||||
to be used by the socket.
|
||||
</para>
|
||||
<table>
|
||||
<title>Available socket types</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Type</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>SOCK_STREAM</entry>
|
||||
<entry>
|
||||
Provides sequenced, reliable, full-duplex, connection-based byte streams.
|
||||
An out-of-band data transmission mechanism may be supported.
|
||||
The TCP protocol is based on this socket type.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SOCK_DGRAM</entry>
|
||||
<entry>
|
||||
Supports datagrams (connectionless, unreliable messages of a fixed maximum length).
|
||||
The UDP protocol is based on this socket type.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SOCK_SEQPACKET</entry>
|
||||
<entry>
|
||||
Provides a sequenced, reliable, two-way connection-based data transmission path for
|
||||
datagrams of fixed maximum length; a consumer is required to read an
|
||||
entire packet with each read call.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SOCK_RAW</entry>
|
||||
<entry>
|
||||
Provides raw network protocol access. This special type of socket
|
||||
can be used to manually construct any type of protocol. A common use
|
||||
for this socket type is to perform ICMP requests (like ping,
|
||||
traceroute, etc).
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>SOCK_RDM</entry>
|
||||
<entry>
|
||||
Provides a reliable datagram layer that does not guarantee ordering.
|
||||
This is most likely not implemented on your operating system.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
<para>
|
||||
<parameter>protocol</parameter> sets the protocol which is either
|
||||
<constant>SOL_UDP</constant> or <constant>SOL_TCP</constant>.
|
||||
The <parameter>protocol</parameter> parameter sets the specific
|
||||
protocol within the specified <parameter>domain</parameter> to be used
|
||||
when communicating on the returned socket. The proper value can be retrieved by
|
||||
name by using <function>getprotobyname</function>. If
|
||||
the desired protocol is TCP, or UDP the corresponding constants
|
||||
<constant>SOL_TCP</constant>, and <constant>SOL_UDP</constant>
|
||||
can also be used.
|
||||
</para>
|
||||
<table>
|
||||
<title>Common protocols</title>
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>Name</entry>
|
||||
<entry>Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>icmp</entry>
|
||||
<entry>
|
||||
The Internet Control Message Protocol is used primarily by gateways
|
||||
and hosts to report errors in datagram communication. The "ping"
|
||||
command (present in most modern operating systems) is an example
|
||||
application of ICMP.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>udp</entry>
|
||||
<entry>
|
||||
The User Datagram Protocol is a connectionless, unreliable,
|
||||
protocol with fixed record lengths. Due to these aspects, UDP
|
||||
requires a minimum amount of protocol overhead.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>tcp</entry>
|
||||
<entry>
|
||||
The Transmission Control Protocol is a reliable, connection based,
|
||||
stream oriented, full duplex protocol. TCP guarantees that all data packets
|
||||
will be received in the order in which they were sent. If any packet is somehow
|
||||
lost during communication, TCP will automatically retransmit the packet until
|
||||
the destination host acknowledges that packet. For reliability and performance
|
||||
reasons, the TCP implementation itself decides the appropriate octet boundaries
|
||||
of the underlying datagram communication layer. Therefore, TCP applications must
|
||||
allow for the possibility of partial record transmission.
|
||||
</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
<para>
|
||||
Returns a socket resource on success, or &false; on error. The actual
|
||||
error code can be retrieved by calling
|
||||
<function>socket_last_error</function>. This error code may be passed to
|
||||
<function>socket_strerror</function> to get a textual explanation of the
|
||||
error.
|
||||
</para>
|
||||
<para>
|
||||
For more information on the usage of <function>socket_create</function>,
|
||||
as well as on the meanings of the various parameters, see the
|
||||
Unix man page socket (2).
|
||||
<function>socket_create</function> Returns a socket resource on success, or &false;
|
||||
on error. The actual error code can be retrieved by calling <function>socket_last_error</function>.
|
||||
This error code may be passed to <function>socket_strerror</function> to get a textual
|
||||
explanation of the error.
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
|
|
|
|||
Loading…
Reference in a new issue