Sockets

Introduo
A extenso socket implementa uma interface de baixo nvel para funes de comunicao sockets baseadas no popular BSD sockets, disponibilizando acionar como um servidor socket ou como um cliente. Para saber mais informaes sobre sockets cliente-servidor, veja stream_socket_client(), stream_socket_server(), fsockopen(), e pfsockopen(). Quando usando estas funes, importante relembrar que enquanto muitas delas tem nomes idnticos equivalentes em C, eles tem frequentemente declaraes diferentes. Por favor tenha certeza lendo as descries para evitar confuso. Aqueles no familiarizados com programao usando socket podem encontrar muito material til nas "man pages" de Unix, e h uma infinidade de tutoriais com informaes usando socket em C na web, muito dos quais podem ser aplicados, com pequenas modificaes, para programao usando socket em PHP. O UNIX Socket FAQ pode ser um bom comeo.

Nota Esta extenso foi movida para o repositrio PECL e no mais distribuida em conjunto com o PHP a partir do PHP 5.3.0.

Sockets

Instalao/Configurao
Dependncias
Nenhuma biblioteca externa necessria para compilar esta extenso.

Instalao
As funes de socket descritas aqui fazem parte de uma extenso do PHP que deve ser habilitada na hora de compilar adicionando a opo --enable-sockets linha de comando configure.

Nota O suporte ao IPv6 foi adicionado no PHP 5.0.0.

Configuraes em Execuo
Esta extenso no define nenhum parmetro de configurao no php.ini.

Tipos Resource
socket_accept(), socket_create_listen() e socket_create() retorna resources de socket.

Sockets

Constantes pr-definidas
As contantes abaixo so definidas por esta extenso e somente estaro disponveis quando a extenso foi compilada com o PHP ou carregada dinamicamente durante a execuo. AF_UNIX ( integer )

AF_INET ( integer )

AF_INET6 ( integer )

SOCK_STREAM ( integer )

SOCK_DGRAM ( integer )

SOCK_RAW ( integer )

SOCK_SEQPACKET ( integer )

SOCK_RDM ( integer )

MSG_OOB ( integer )

MSG_WAITALL ( integer )

MSG_PEEK ( integer )

MSG_DONTROUTE ( integer )

MSG_EOR ( integer )

MSG_EOF ( integer )

SO_DEBUG ( integer )

Sockets

SO_REUSEADDR ( integer )

SO_KEEPALIVE ( integer )

SO_DONTROUTE ( integer )

SO_LINGER ( integer )

SO_BROADCAST ( integer )

SO_OOBINLINE ( integer )

SO_SNDBUF ( integer )

SO_RCVBUF ( integer )

SO_SNDLOWAT ( integer )

SO_RCVLOWAT ( integer )

SO_SNDTIMEO ( integer )

SO_RCVTIMEO ( integer )

SO_TYPE ( integer )

SO_ERROR ( integer )

SOL_SOCKET ( integer )

PHP_NORMAL_READ ( integer )

PHP_BINARY_READ ( integer )

SOL_TCP ( integer ) Sockets 5

SOL_UDP ( integer )

Sockets

Exemplos

Exemplo #1 - Exemplo de socket: Simples servidor TCP/IP Este exemplo mostra uma simples troca de informaes do servidor. Alterar as variveis address e port para o conjunto da sua configurao e execuo. Voc deve ento conectar o servidor com uma linha de comando similiar a: telnet 192.168.1.53 10000 (onde o endereo e a porta partem da sua configurao). Algo que voc digitar ento ir sair no lado do servidor, e mostrar isso para voc. Para desconectar, digite 'quit'.
#!/usr/local/bin/php -q <?php error_reporting(E_ALL); /* Allow the script to hang around waiting for connections. */ set_time_limit(0); /* Turn on implicit output flushing so we see what we're getting * as it comes in. */ ob_implicit_flush(); $address = '192.168.1.53'; $port = 10000; if (($sock = socket_create(AF_INET, SOCK_STREAM, SOL_TCP)) === false) { echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n"; } if (socket_bind($sock, $address, $port) === false) { echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n"; } if (socket_listen($sock, 5) === false) { echo "socket_listen() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n"; } do { if (($msgsock = socket_accept($sock)) === false) { echo "socket_accept() failed: reason: " . socket_strerror(socket_last_error($sock)) . "\n"; break; } /* Send instructions. */ $msg = "\nWelcome to the PHP Test Server. \n" . "To quit, type 'quit'. To shut down the server type 'shutdown'.\n"; socket_write($msgsock, $msg, strlen($msg)); do { if (false === ($buf = socket_read($msgsock, 2048, PHP_NORMAL_READ))) {

Sockets

echo "socket_read() failed: reason: " . socket_strerror(socket_last_error($msgsock)) . "\n"; break 2; } if (!$buf = trim($buf)) { continue; } if ($buf == 'quit') { break; } if ($buf == 'shutdown') { socket_close($msgsock); break 2; } $talkback = "PHP: You said '$buf'.\n"; socket_write($msgsock, $talkback, strlen($talkback)); echo "$buf\n"; } while (true); socket_close($msgsock); } while (true); socket_close($sock); ?>

Exemplo #2 - Exemplo de Socket: Simples cliente TCP/IP Este exemplo mostra um simples, one-shot cliente HTTP. Isso simplesmente conecta uma pgina, envia um cabealho de requisio, mostra a resposta, e sai.
<?php error_reporting(E_ALL); echo "<h2>TCP/IP Connection</h2>\n"; /* Get the port for the WWW service. */ $service_port = getservbyname('www', 'tcp'); /* Get the IP address for the target host. */ $address = gethostbyname('www.example.com'); /* Create a TCP/IP socket. */ $socket = socket_create(AF_INET, SOCK_STREAM, SOL_TCP); if ($socket === false) { echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n"; } else { echo "OK.\n"; } echo "Attempting to connect to '$address' on port '$service_port'..."; $result = socket_connect($socket, $address, $service_port); if ($result === false) { echo "socket_connect() failed.\nReason: ($result) " . socket_strerror(socket_last_error($socket)) . "\n"; } else {

Sockets

echo "OK.\n"; } $in = "HEAD / HTTP/1.1\r\n"; $in .= "Host: www.example.com\r\n"; $in .= "Connection: Close\r\n\r\n"; $out = ''; echo "Sending HTTP HEAD request..."; socket_write($socket, $in, strlen($in)); echo "OK.\n"; echo "Reading response:\n\n"; while ($out = socket_read($socket, 2048)) { echo $out; } echo "Closing socket..."; socket_close($socket); echo "OK.\n\n"; ?>

Sockets

Socket Errors
A extenso socket foi escrita para disponibilizar uma interface til e poderosa para sockets BSD. Tem-se notado que as funes funcionam igualmente bem em Win32 e Unix. Quase todas as funes de sockets devem falhar sob certas condies e portanto emite uma mensagem E_WARNING descrevendo o erro. De vez em quando isso no acontece para desespero do desenvolvedor. Por exemplo a funo socket_read() deve de repente emitir uma mensagem E_WARNING porque a conexo foi quebrada inesperadamente. comum esconder as mensagens de warning com o operador @ e pegar o cdigo de erro dentro da aplicao com a funo socket_last_error(). Voc deve chamar a funo socket_strerror() com esse cdigo de erro para retornar uma string descrevendo o erro. Veja sua descrio para mais informaes.

Nota A mensagem de E_WARNING gerada pela extenso socket esto em ingls dificilmente a mensagem de erro retornada ira aparecer correto dependendo da localidade padro ( LC_MESSAGES ):
Warning - socket_bind() unable to bind address [98]: Die Adresse wird bereits verwendet

Sockets

10

Funes para Socket

Sockets

11

socket_accept
socket_accept -- Aceita uma conexo com um socket

Descrio
resource socket_accept ( resource $socket ) Aps o socket socket ter sido criado usando socket_create(), passar um nome com socket_bind(), e dizer para listar conexes com socket_listen(), essa funo ir aceitar conexes vindas neste socket. Uma vez que uma conexo com sucesso feita, um novo "resource" do socket retornado, que deve ser usado para comunicao. Se h mltiplas conexes na fila do socket, a primeira ir ser usada. Se no h conexes pendentes, socket_accept() ir bloquear at que uma conexo esteja presente. Se socket no for desbloqueado usando socket_set_blocking() ou socket_set_nonblock(), ir retornar FALSE. O socket resource retornado por socket_accept() no deve ser usado para aceitar novas conexes. A escuta original, socket, de qualquer modo, permanecer aberta e deve ser reutilizada.

Parmetros
socket

Um vlido resource de socket criado com socket_create().

Valor Retornado
Returns a new socket resource on success, or FALSE on error. The actual error code can be retrieved by calling socket_last_error(). This error code may be passed to socket_strerror() para pegar uma explicao textual do erro.

Veja Tambm

socket_connect() socket_listen() socket_create() socket_bind() socket_strerror()

Sockets

12

socket_bind
socket_bind -- Passa um nome para o socket

Descrio
bool socket_bind ( resource $socket, string $address [, int $port ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

socket_bind() passa o nome dado em address para o socket descrito por socket, que deve ser um resource socket vlido criado com socket_create(). O parmetro address qualquer endereo IP na notao "dotted-quad" (ex. 127.0.0.1 ), se o socket da famlia AF_INET; ou o pathname de um Unix-domain socket, se o socket da famlia AF_UNIX. O parmetro port somente usado quando estiver conectando com um socket AF_INET, e determina a porta no host remoto para o qual a conexo deve ser feita. Retorna TRUE em caso de sucesso ou FALSE em falhas. O cdigo de erro pode ser retornado com socket_last_error(). Esse cdigo deve ser passado para socket_strerror() para pegar uma explicao textual do erro. Note que socket_last_error() reportado para retornar um cdigo de erro invlido no caso de voc estar tentando passar um socket para um endereo errado que no pertence sua mquina Windows 9x/ME. Veja tambm socket_connect(), socket_listen(), socket_create(), socket_last_error() e socket_strerror().

Sockets

13

socket_clear_error
socket_clear_error -- Limpa o erro no socket ou o ltimo cdigo de erro

Descrio
void socket_clear_error ( [ resource $socket ] ) Essa funo limpa o cdigo de erro dado no socket ou o ltimo erro de socket global se nenhum for especificado. Essa funo permite explicitamente resetar qualquer valor do cdigo de erro do socket ou da extenso global do ltimo cdigo de erro. Isso deve ser til para detectar dentro de uma parte da aplicao se um erro ocorreu ou no.

Parmetros
socket

Um vlido resource de socket criado com socket_create().

Valor Retornado
No h valor retornado.

Veja Tambm

socket_last_error() socket_strerror()

Sockets

14

socket_close
socket_close -- Fecha um socket resource

Descrio
void socket_close ( resource $socket )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

socket_close() fecha o socket resource dado por socket.

Nota socket_close() no pode ser usado em arquivos PHP file resources criados com fopen(), popen(), fsockopen(), ou pfsockopen(); isso serve parapara sockets criados com socket_create() ou socket_accept().

Veja tambm socket_bind(), socket_listen(), socket_create() e socket_strerror().

Sockets

15

socket_connect
socket_connect -- Inicializa uma conexo em um socket

Descrio
bool socket_connect ( resource $socket, string $address [, int $port ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Inicializa uma conexo usando o socket resource socket, que deve ser um vlido socket resource criado com socket_create(). O parmetro address qualquer endereo IP na notao "dotted-quad" (ex. 127.0.0.1 ), se o socket da famlia AF_INET; ou o pathname de um Unix-domain socket, se o socket da famlia AF_UNIX. O parmetro port somente usado quando estiver conectando com um socket AF_INET, e determina a porta no host remoto para o qual a conexo deve ser feita. Retorna TRUE em caso de sucesso ou FALSE em falhas. O cdigo de erro pode ser retornado com socket_last_error(). Esse cdigo deve ser passado para socket_strerror() para pegar uma explicao textual do erro. Veja tambm socket_bind(), socket_listen(), socket_create(), socket_last_error() e socket_strerror().

Sockets

16

socket_create_listen
socket_create_listen -- Abre uma porta do socket para aceitar conexes

Descrio
resource socket_create_listen ( int $port [, int $backlog ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Essa funo significa facilidade na tarefa de criao de um novo socket que esteja na escuta somente para aceitar novas conexes. socket_create_listen() cria um novo socket resource do tipo AF_INET escutando all interfaces loacis na porta especificada esperando por novas conexes. O parmetro backlog define o comprimento mximo da fila de espera de conexes pendentes at onde ela deve crescer. SOMAXCONN deve ser passado como o parmetro backlog, veja socket_listen() para maiores informaes. socket_create_listen() retorna um novo socket resource em caso de sucesso ou FALSE em caso de erro. O cdigo de erro pode ser retornado com socket_last_error(). Esse cdigo deve ser passado para socket_strerror() para pegar uma explicao textual do erro.

Nota Se voc quer criar um socket com somente escutas em certas interfaces voc deve precisar usar socket_create(), socket_bind() e socket_listen().

Veja tambm socket_create(), socket_bind(), socket_listen(), socket_last_error() e socket_strerror().

Sockets

17

socket_create_pair
socket_create_pair -- Cria um par de sockets irreconhecveis e armazena-os no fds.

Descrio
bool socket_create_pair ( int $domain, int $type, int $protocol, array $&fd )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Aviso Esta funo no est documentada; somente a lista de argumentos est disponvel.

Sockets

18

socket_create
socket_create -- Cria um socket (endpoint para comunicao)

Descrio
resource socket_create ( int $domain, int $type, int $protocol ) Cria e retorna um socket resource, tambm referenciado como um endpoint para comunicao. Uma conexo tpica de rede feita em cima de 2 sockets, um realizando o papel do cliente, e o outro realizando o papel de servidor. O parmetro domain especifica a famlia do protocolo para ser usado pelo socket.

Famlias disponveis Endereos/Protocolos Domnio AF_INET Descrio IPv4 baseado nos protocolos de Internet. TCP e UDP so protocolos comuns dessa famlia de protocolos. IPv6 baseado nos protocolos de Internet. TCP e UDP so protocolos comuns dessa famlia de protocolos. Suporta adicionado no PHP 5.0.0. Famlia de protocolos de comunicao local. Alta eficincia e baixo sobrecarga fazem deste uma forte forma de IPC (Processos internos de comunicao).

AF_INET6

AF_UNIX

O parmetro type seleciona o tipo de comunicao para ser usado pelo socket.

Tipos de socket disponveis Tipo SOCK_STREAM Descrio Fornece sequencial, seguro, e em ambos os sentidos, conexes baseadas em "byte streams". Dados "out-of-band" do mecanismo de transmisso devem ser suportados. O protocolo TCP baseado neste tipo de socket. Suporta diagrama de dados (baixa conexo, 19

SOCK_DGRAM Sockets

mensagens inconfiveis de um comprimento mximo fixo). O protocolo UDP protocol baseado neste tipo de socket. SOCK_SEQPACKET Fornece um sequencial, seguro, e em duas direes de tipos de conexes para transmisso de dados endereados para o diagrama de dados de comprimento mximo fixo; um consumidor requerido para ler um pacote inteiro com cada chamada de leitura. Fornece um protocolo de rede de acesso rpido. Este tipo especial de socket pode ser usado manualmente para construir algum tipo de protocolo. Um uso comum para esse tipo de socket desempenhar requisies ICMP (como ping, traceroute, etc). Fornece uma camada seguro que no garante ordenao. Isso comumente no implementado no seu sistema operacional.

SOCK_RAW

SOCK_RDM

O parmetro protocol configura o protocolo especificado dentro do domain especificado para ser usado quando houver comunicao de retorno com o socket. O valor da propriedade pode ser retornado pelo nome usando getprotobyname(). Se o protocolo desejado TCP, ou UDP as constantes correspondentes so SOL_TCP, e SOL_UDP podem tambm ser usadas.

Protocolos comuns Nome icmp Descrio O protocolo de controle de mensagens internet "The Internet Control Message Protocol" usado primariamente por gateways e hosts para reportar erros no diagrama de dados de comunicao. O comando "ping" (presente em muitos modernos sistemas operacionais) um exemplo aplicado de ICMP. O protocolo de diagrama de dados de usurios "User Datagram Protocol" de conexo baixa, inseguro, protocolo com comprimento fixo. Dois destes aspectos, UDP requer uma quantidade mnima de sobrecarga de protocolo. 20

udp

Sockets

tcp

O protocolo de controle de transmisso uma conexo, seguro, fluxo orientado, e protocolo de ida e volta. TCP garante que todos os pacotes de dados iro ser recebidos na ordem que eles so enviados. Se algum pacote est perdido de alguma maneira durante a comunicao, TCP ir automaticamente retransmitir o pacote at que o host de destino reconhea aquele pacote. Por razes de segurana e performance, o TCP implementa nele prprio decises apropriadas de limite de octetos do diagrama de dados abaixo da camada de comunicao. Portanto, aplicaes TCP devem permitir para possibilidades de registro de transmisses.

socket_create() retorna um socket resource em caso de sucesso, ou FALSE em caso de erro. O cdigo de erro atual pode ser retornado chamando socket_last_error(). Esse cdigo de erro deve ser passado para socket_strerror() para pegar uma explicao textual do erro.

Nota Se um invlido domain ou type dado, socket_create() padro para AF_INET e SOCK_STREAM respectivamente e adicionamente emitem uma mensagem E_WARNING.

Veja tambm socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error(), e socket_strerror().

Sockets

21

socket_get_option
socket_get_option -- Pega opes de socket para o socket

Descrio
mixed socket_get_option ( resource $socket, int $level, int $optname )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Aviso Esta funo no est documentada; somente a lista de argumentos est disponvel.

Nota Essa funo para ser usada chamando socket_getopt() primeiramente para PHP 4.3.0

Sockets

22

socket_getpeername
socket_getpeername -- Pergunta ao lado remoto do socket dado qual deve ser o resultado em host/port ou no endereo UNIX filesystem, dependendo deste tipo.

Descrio
bool socket_getpeername ( resource $socket, string $&addr [, int $&port ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Se o socket dado do tipo AF_INET ou AF_INET6, socket_getpeername() ir retornar o peers (remote) IP address na notao apropriada (ex. 127.0.0.1 ou fe80::1 ) no parmetro address e, se o parmetro opcional port est presente, tambm o associa porta. Se o socket dado do tipo AF_UNIX, socket_getpeername() ir retornar o endereo UNIX filesystem (ex. /var/run/daemon.sock ) no parmetro address.

Nota socket_getpeername() no deve ser usado com sockets AF_UNIX criados com socket_accept(). Somente sockets criados com socket_connect() ou um socket de servidor primrio seguindo uma chamada para socket_bind() ir retornar valores significativos.

Retorna TRUE em caso de sucesso ou FALSE em falhas. socket_getpeername() deve tambm retornar FALSE se o tipo de socket no algum destes AF_INET, AF_INET6, ou AF_UNIX, no caso o ltimo cdigo de erro do socket no atualizado. Veja tambm socket_getsockname(), socket_last_error() e socket_strerror().

Sockets

23

socket_getsockname
socket_getsockname -- Pergunta o lado local dado do socket no qual deve retornar resultados no host/port ou no endereo UNIX filesystem, dependendo do tipo.

Descrio
bool socket_getsockname ( resource $socket, string $&addr [, int $&port ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Se o socket dado do tipo AF_INET ou AF_INET6, socket_getsockname() ir retornar o endereo IP local IP address na notao apropriada (ex. 127.0.0.1 ou fe80::1 ) no parmetro address e, se o parmetro opcional port est presente, tambm associa-o porta. Se o socket dado do tipo AF_UNIX, socket_getsockname() ir retornar o endereo UNIX filesystem (ex. /var/run/daemon.sock ) no parmetro address.

Nota socket_getsockname() no deve ser usado com sockets AF_UNIX criados com socket_connect(). Somente sockets criados com socket_accept() ou sockets de servidores primrios seguidos de uma chamada para socket_bind() iro retornar valores significativos.

Retorna TRUE em caso de sucesso ou FALSE em falhas. socket_getsockname() deve tambm retornar FALSE se o tipo de socket no algum destes AF_INET, AF_INET6, ou AF_UNIX, no caso o ltimo cdigo de erro do socket no atualizado. Veja tambm socket_getpeername(), socket_last_error() e socket_strerror().

Sockets

24

socket_last_error
socket_last_error -- Retorna o ltimo erro no socket

Descrio
int socket_last_error ( [ resource $socket ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Essa funo retorna um cdigo de erro do socket. Se o socket resource passado para esta funo, o ltimo erro que ocorreu neste socket em particular retornado. Se o socket resource omitido, o cdigo de erro da ltima falha na funo de socket retornado. O ltimo em particular til como socket_create() que no retorna uma falha no socket e socket_select() que pode falhar por razes no diretamente vinculadas com um socket em particular. O cdigo de erro conveniente ser colocado para socket_strerror() que retorna uma string descrevendo o cdigo de erro dado.
<?php if (false == ($socket = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP))) { die("Couldn't create socket, error code is: " . socket_last_error() . ",error message is: " . socket_strerror(socket_last_error())); } ?>

Nota socket_last_error() no limpa o cdigo de erro, use socket_clear_error() para este propsito.

Sockets

25

socket_listen
socket_listen -- Abre escuta para uma conexo no socket

Descrio
bool socket_listen ( resource $socket [, int $backlog ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Aps o socket socket ter sido criado usando socket_create() e associado para um nome com socket_bind(), ele deve dizer para aguardar por escuta em conexes que iro entrar socket. Um mximo de backlog em conexes entrantes iro ser listadas para este processamento. Se uma requisio de conexo chegar com um limite de clientes devem receber um erro com uma identificao de ECONNREFUSED, ou, se o protocolo abaixo suporta retransmisso, a requisio deve ser ignorada de forma at serem bem sucedidas.

Nota O mximo nmero passado para o parmetro backlog altamente dependente da plataforma abaixo. No linux, isso silenciosamente truncado para SOMAXCONN. No win32, se passado SOMAXCONN, o disponibilizador de servio abaixo responsvel pelo socket ir configurar o backlog para o valor mximo reasonable. No h uma condio para procurar o valor do backlog atual nesta plataforma.

socket_listen() aplicvel somente para sockets do tipo SOCK_STREAM ou SOCK_SEQPACKET. Retorna TRUE em caso de sucesso ou FALSE em falhas. O cdigo de erro pode ser retornado com socket_last_error(). Isso cdigo deve ser passado para socket_strerror() para pegar uma explicao textual do erro. Veja tambm socket_accept(), socket_bind(), socket_connect(), socket_create() e socket_strerror().

Sockets

26

socket_read
socket_read -- L um comprimento mximo de bytes de um socket

Descrio
string socket_read ( resource $socket, int $length [, int $type ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

A funo socket_read() l o socket resource socket criado pelas funes socket_create() ou socket_accept(). O nmero mximo de bytes lidos especificado pelo parmetro length. Caso contrrio voc pode usar \r, \n, uo \0 para finalizar a leitura (dependendo do parmetro type, veja abaixo). socket_read() retorna dados como uma string em caso de sucesso, ou FALSE em caso de erro. O cdigo de erro pode ser retornado com socket_last_error(). Esse cdigo deve ser passado para socket_strerror() para pegar uma explicao textual do erro.

Nota socket_read() deve retornar uma string de comprimento zero ("") indicando o fim da comunicao (ex. o ponto final remoto encerra a conexo).

O parmetro opcional type usado com constantes: PHP_BINARY_READ - usa a funo do sistema read(). Seguro para leitura de dados binrios. (Padro no PHP >= 4.1.0) PHP_NORMAL_READ - l at o final em \n ou \r. (Padro no PHP <= 4.0.6)

Veja tambm socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_last_error(), socket_strerror() e socket_write().

Sockets

27

socket_recv
socket_recv -- Recebe dados de um socket conectado

Descrio
int socket_recv ( resource $socket, string &$buf, int $len, int $flags )

Aviso Esta funo no est documentada; somente a lista de argumentos est disponvel.

Sockets

28

socket_recvfrom
socket_recvfrom -- Recebe dados de um socket, conectado ou no

Descrio
int socket_recvfrom ( resource $socket, string $&buf, int $len, int $flags, string $&name [, int $&port ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Aviso Esta funo no est documentada; somente a lista de argumentos est disponvel.

Sockets

29

socket_select
socket_select -- Executa a chamada de sistema select() nos arrays dados de sockets com um timeout especificado

Descrio
int socket_select ( array $&read, array $&write, array $&except, int $tv_sec [, int $ tv_usec ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

socket_select() aceita arrays de sockets e aguarda at que seu status seja alterado. Estes vem com "background" de sockets BSD ir reconhecer aquele array de socket resource so de fato a chamada ao arquivo descritor de configurao (fds). Trs arrays independentes de socket resources so observados. A lista de sockets no array read ir ser mostrada para ver se o caractere disponvel anterior leitura (mais precisamente, para ver se a leitura no est obstruda - em particular, um socket resource est tambm no fim-de-arquivo (EOF) , neste caso o socket_read() ir retornar uma string com comprimento zero. A lista de sockets no array write ir ser visualizada para mostrar se no uma escrita no est obstruda. A lista de sockets no array except ir mostrar caso haja excees.

Aviso Na sada, os arrays so modificados para indicar qual socket resource atualmente alterou seu status.

Voc no precisa passar cada array para socket_select(). Voc pode deix-los de fora e usar um array vazio ou NULL ao invs disso. Tambm no se esquea que esses arrays so passados by reference e iro ser modificados aps o retorno de socket_select().

Exemplo #1 - Exemplo de socket_select()

<?php /* Prepare the read array */

Sockets

30

$read = array($socket1, $socket2); $num_changed_sockets = socket_select($read, $write = NULL, $except = NULL, 0); if ($num_changed_sockets === false) { /* Error handling */ } else if ($num_changed_sockets > 0) { /* At least at one of the sockets something interesting happened */ } ?>

Nota Devido a uma limitao no atual Zend Engine no possvel passar um modificador de constante como NULL diretamente como parmetro para uma funo que tem exceo para este parmetro sendo passado por referncia. Ao invs disso use uma varivel temporria ou uma expresso com o leftmost member sendo uma varivel temporria: Exemplo #2 - Usando NULL com socket_select()
<?php socket_select($r, $w, $e = NULL, 0); ?>

O tv_sec e tv_usec juntos formam o parmetro timeout. O timeout o limite mximo da quantidade de tempo passado antes do retorno de socket_select(). tv_sec deve ser zero , causando o retorno imediato de socket_select(). Isso til para polling. Se tv_sec NULL (sem timeout), socket_select() pode bloquear definitivamente. Em caso de sucesso socket_select() retorna o nmero de socket resorces contidos nos arrays modificados, que deve ser zero se alguma coisa interessante acontecer antes do timeout expirar. Em caso de erro, FALSE retornado. O cdigo do erro pode ser retornado com socket_last_error().

Nota Tenha certeza de usar o operador === quando checar por um erro. Desde de que socket_select() deve retornar 0 a comparao com == deve retornar TRUE: Exemplo #3 - Entendendo resultados de socket_select()
<?php if (false === socket_select($r, $w, $e = NULL, 0)) { echo "socket_select() failed, reason: " . socket_strerror(socket_last_error()) . "\n"; }

Sockets

31

?>

Nota Esteja consciente que algumas implementaes de sockets precisam ser manuseadas com muito cuidado. As regras bsicas: Voc deve sempre tentar usar socket_select() sem timeout. Seu programa no deve fazer nada se no h dados disponveis. Cdigos que dependem de timeouts no so usualmente portveis e dificultam o debug. No socket resource deve ser adicionado alguma configurao se voc no pretende checar o resultado aps a chamada de socket_select(), e responder de forma apropriada. Aps o retorno de socket_select(), todos os sockets resources em todos os arrays devem ser checados. Algum socket resource que est disponvel para escrita deve ser escrito, e algum socket resource disponvel para leitura deve ser lido. Se voc est lendo/escrevendo um retorno de socket em array esteja consciente que eles no necessariamente esto lendo/escrevendo a quantidade completa de dados que voc requisitou. Esteja preparado para somente habilitar para leitura/escrita um nico byte. Isso comum na grande maioria de implementaes de socket que pegam excees atravs do except array est fora do limite de dados recebidos no socket.

Veja tambm socket_read(), socket_write(), socket_last_error() e socket_strerror().

Sockets

32

socket_send
socket_send -- Envia dados para um socket conectado

Descrio
int socket_send ( resource $socket, string $buf, int $len, int $flags )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

A funo socket_send() envia len bytes para o socket socket de buf O valor de flags pode ser alguma combinao ORed das seguintes: Possveis valores para flags 0x1 0x2 0x4 0x8 0x100 Processo OOB (out-of-band) de dados Ver mensagens de entrada. Bypass routing, usa interface direta. Fluxo completo de dados. Transao completa de dados.

Veja tambm socket_sendmsg() e socket_sendto().

Sockets

33

socket_sendto
socket_sendto -- Envia uma mensagem para o socket, se estiver conectado ou no

Descrio
int socket_sendto ( resource $socket, string $buf, int $len, int $flags, string $addr [, int $port ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

A funo socket_sendto() envia len bytes de buf atravs do socket socket para a port no endereo addr O valor de flags pode ser um dos seguintes: Valores possveis para flags 0x1 0x2 0x4 0x8 0x100 Processo OOB (out-of-band) de dados. Ver mensagens de entrada. Bypass routing, usa interface direta. Fluxo completo de dados. Transao completa de dados.

Exemplo #1 - Exemplo socket_sendto()

<?php $sh = socket_create(AF_INET,SOCK_STREAM,SOL_TCP); if (socket_bind($sh, '127.0.0.1', 4242)) { echo "Socket bound correctly"; } $buf = 'Test Message'; $len = strlen($buf); if (socket_sendto($sh, $buf, $len, 0x100, '192.168.0.2', 4242) !== FALSE) { echo "Message sent correctly"; } socket_close($sh);

Sockets

34

?>

Veja tambm socket_send() e socket_sendmsg().

Sockets

35

socket_set_block
socket_set_block -- Configura o modo bloqueio em um socket resource

Descrio
bool socket_set_block ( resource $socket )

Aviso Esta funo no est documentada; somente a lista de argumentos est disponvel.

Retorna TRUE em caso de sucesso ou FALSE em falhas. Veja tambm socket_set_nonblock() e socket_set_option()

Sockets

36

socket_set_nonblock
socket_set_nonblock -- Configura o modo nonblocking para o arquivo de descrio fd

Descrio
bool socket_set_nonblock ( resource $socket )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Aviso Esta funo no est documentada; somente a lista de argumentos est disponvel.

Sockets

37

socket_set_option
socket_set_option -- Configura opes de socket para o socket

Descrio
bool socket_set_option ( resource $socket, int $level, int $optname, mixed $optval )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

Aviso Esta funo no est documentada; somente a lista de argumentos est disponvel.

Nota Essa funo usado chamando socket_setopt() primariamente para PHP 4.3.0

Sockets

38

socket_shutdown
socket_shutdown -- Fecha um socket para receber, enviar dados ou ambos.

Descrio
bool socket_shutdown ( resource $socket [, int $how ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

A funo socket_shutdown() permite que voc pare a entrada, sada ou todos os dados (este o padro) de serem enviados atravs do socket O valor de how pode ser um dos seguintes: possible values for how 0 1 2 Fecha o socjet para leitura Fecha o socket para escrita Fecha o socket para leitura e escrita

Sockets

39

socket_strerror
socket_strerror -- Retorna uma string descrevendo o erro do socket

Descrio
string socket_strerror ( int $errno )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

socket_strerror() pega como parmetro errno um cdigo de erro de socket retornado por socket_last_error() e retorna a explicao em texto correspondente. Isso faz com que isso tenha uma imagem de sada mais agradvel porque alguma coisa no funciona; for exemplo, ao invs de ter que fazer procura de uma incluso de um arquivo do sistema do que '-111' significa, voc somente passa isso para socket_strerror(), e ele lhe fala o que acontece.

Exemplo #1 - Exemplo de socket_strerror()

<?php if (false == ($socket = @socket_create(AF_INET, SOCK_STREAM, 0))) { echo "socket_create() failed: reason: " . socket_strerror(socket_last_error()) . "\n"; } if (false == (@socket_bind($socket, '127.0.0.1', 80))) { echo "socket_bind() failed: reason: " . socket_strerror(socket_last_error($socket)) . "\n"; } ?>

A sada esperada do exemplo acima (assumindo que o script no est rodando com privilgios de root):
socket_bind() failed: reason: Permission denied

Veja tambm socket_accept(), socket_bind(), socket_connect(), socket_listen(), e socket_create().

Sockets

40

socket_write
socket_write -- Escreve em um socket

Descrio
int socket_write ( resource $socket, string $buffer [, int $length ] )

Aviso Esta funo EXPERIMENTAL. O comportamento desta funo, seu nome, incluindo toda documentao pode ser modificado sem aviso em futuras verses do PHP. Esta funo deve ser usada por sua prpria conta e risco.

A funo socket_write() escreve em um socket socket de buffer. O parmetro opcional length pode especificar um comprimento alternativo de bytes escritos para o socket. Se esse comprimento maior do que o comprimento do buffer, isso ser silenciosamente truncado para o comprimento do buffer. Retorna o nmero de bytes escritos com sucesso para o socket ou FALSE em um erro. O cdigo de erro pode ser retornado com socket_last_error(). Esse cdigo deve ser passado para socket_strerror() para pegar uma explicao textual do erro.

Nota socket_write() no necessariamente escreve todos os bytes dados do buffer. Isso valido, dependendo da rede, buffers etc., somente uma quantidade segura de dados, sempre um byte, escrito embora seu buffer seja maior. Voc deve prestar ateno para involuntariamente esquecer de transmitir o restante dos seus dados.

Nota Isso perfeitamente vlido para socket_write() retornar zero que significa que no tem bytes para escrever. Tenha certeza de usar o operador === para checar por FALSE em caso de um erro.

Veja tambm socket_accept(), socket_bind(), socket_connect(), socket_listen(), socket_read() e socket_strerror().

Sockets

41