Chapitre 2 : Structures résistives élémentaires : optimisation des étapes
2.4. Stabilisation de la microstructure du nickel par recuit pré-oxydation
A API do S3L oferece um conjunto de func~oes de escrita e leitura sobre socketsbastante semelhantes as func~oes homologas de Berkeley. O objectivo dessas func~oes e proporcionar ao utilizador de sockets as qualidades de servico que adv^em da utilizac~ao de mensagens S3L (Privacidade, Autenticac~ao, Integridade, Compress~ao, parametrizac~ao do tempo de vida).
Basicamente, as func~oes do S3L assentam em chamadas as func~oes equivalentes de Berkeley, mas escondem do invocador os detalhes de assemblagem e desassemblagem das mensagens S3L que ir~ao transportar os dados do utilizador.
As semelhancas sintacticas entre as func~oes S3L e de Berkeley facilitam bastante a reconvers~ao de aplicac~oes entre os dois grupos de func~oes. Registe{se, todavia, que, em termos sem^anticos, a equival^encia n~ao e total:
as func~oes S3L suportam, por enquanto, apenas sockets do tipo SOCK STREAM e
SOCK DGRAM;
n~ao e possvel de nir as func~oes S3L como automaticamente recomecaveis face a ocorr^encia de sinais, ao contrario do que pode ser feito com as func~oes de Berkeley atraves da primitivasiginterrupt;
um eventual par^ametro que indique o numero de bytes a ler e desprezado porque uma func~ao S3L de leitura consome uma (ou mais, c.f. o caso) mensagem S3L completa, cuja dimens~ao e determinada pela analise do seu cabecalho; de igual modo, um valor de retorno que indique o numero de bytes escrito leva em considerac~ao o numero total de bytes da mensagem S3L assemblada e n~ao dos dados que o utilizador forneceu.
Func~oes de Escrita
Nome: S3Lwrite{ escreve uma mensagem S3L para um descritor de cheiro S3Lwrite
Sinopse:
#include <s3lsocket.h>
int S3Lwrite (int fd, char *buf, size t count, S3LCtx *ctx);
Descric~ao:
A func~ao S3Lwrite e analoga a func~ao write, excepto que buf e encapsulado
numa mensagem S3L com base no contexto ctx, antes de ser escrita parafd.
Valores de retorno:
A func~ao retorna o numero de bytes escritos se bem sucedida (esse numero corres- ponde a dimens~ao da mensagem S3L, sendo, invariavelmente, diferente decount).
Caso contrario retorna-1 e errnoe modi cada de acordo com o erro espec co
em causa.
Erros: Os mesmos valores produzidos por writee mais alguns espec cos: EINVAL:
ctxinvalido; EPROTO:
assemblagem da mensagem S3L falhou ou escrita da mensagem S3L com- pleta falhou;
Ver tambem:
write,S3Lread
Nome: S3Lsend, S3Lsendto, S3Lsendmsg{ escrevem mensagens S3L para um descritorS3Lsend
desocket S3Lsendto
S3Lsendmsg
Sinopse:
#include <s3lsocket.h>
int S3Lsend (int fd, void *msg, int len, unsigned int flags, S3LCtx *ctx);
int S3Lsendto (int fd, void *msg, int len, unsigned int flags, const struct sockaddr *to, int tolen, void *ctx);
int S3Lsendmsg (int fd, struct msghdr *msg, unsigned int flags, S3LCtx *ctx);
Descric~ao:
As func~oes S3Lsend e S3Lsendto s~ao semelhantes as func~oes send e sendto,
respectivamente, excepto que a mensagem msg e encapsulado numa mensagem
S3L, com base no contextoctx, antes de ser escrita em fd.
A func~ao S3Lsendtopode ser usada para enviar mensagens S3L ponto{a{ponto
ou multiponto, conforme o tipo de endereco IP fornecido no camposin addr do
convertido para S3LCtx * ou S3LMCtx *. Note{se ainda que o envio de mensa-
gens S3L multiponto atraves deS3Lsendtoesta limitado asocketsfdde domnio
AF INETe tipoSOCK DGRAM.
A func~ao S3Lsendmsg e semelhante a func~ao sendmsg, excepto que o vector msg->msg iov e convertido num vector equivalente de mensagens S3L, assem-
bladas com base no contexto ctx.
Valores de retorno:
As func~oes retornam o numero de bytes enviados se bem sucedidas (esse numero corresponde a dimens~ao da mensagem S3L, sendo, invariavelmente, diferente de
len). Caso contrario retornam -1 e errno e modi cada de acordo com o erro
espec co em causa.
Erros: Os mesmos valores produzidos porsend,sendtoe sendmsge mais alguns valores
espec cos:
EINVAL:
ctxinvalido; EPROTO:
assemblagem da mensagem (ou vector de mensagens) S3L falhou ou es- crita da mensagem (ou vector de mensagens) S3L completa(o) falhou; Ver tambem:
send,sendto,sendmsg,S3Lrecv,S3Lrecvfrom,S3Lrecvmsg
Nome: S3Lwritev { escreve um vector de mensagens S3L para um descritor de chei-
ro S3Lwritev
Sinopse:
#include <s3lsocket.h>
int S3Lwritev (int fd, struct iovec *vector, size t count, S3LCtx *ctx);
Descric~ao:
A func~aoS3Lwriteve semelhante a func~aowritev, excepto que o vectorvector
e convertido num vector equivalente de mensagens S3L, assembladas com base no contexto ctxe posteriormente escritas em fd.
Valores de retorno:
A func~ao retorna o numero total de bytes enviados se bem sucedida (esse numero corresponde a dimens~ao do vector de mensagens S3L, sendo, invariavelmente, diferente da soma dos camposiov lendo vector original). Caso contrario retorna -1e a variavel errnoe modi cada de acordo com o erro espec co em causa.
Erros: Os mesmos valores produzidos por writeve mais alguns valores espec cos: EINVAL:
ctxinvalido; EPROTO:
assemblagem do vector de mensagens S3L falhou ou escrita do vector de mensagens S3L completo falhou;
Ver tambem:
writev,S3Lreadv
Func~oes de Leitura
Nome: S3Lread{ l^e uma mensagem S3L de um descritor de cheiro S3Lread
Sinopse:
#include <s3lsocket.h>
int S3Lread (int fd, char *buf, size t count, S3LCtx *ctx);
Descric~ao:
A func~aoS3Lreade analoga a func~aoread, excepto que embufs~ao colocados os
dados do utilizador integrados na mensagem S3L lida defd.
O par^ametro count permanece por raz~oes de compatibilidade de sintaxe, n~ao
sendo determinante no numero de bytes lidos, uma vez que S3Lread l^e sempre
uma mensagem S3L completa. Contudo, espera{se quebuf tenha pelo menos a
dimens~ao dada porcount.
O contexto S3L de recepc~ao e gravado emctx, permitindo a sua eventual reuti-
lizac~ao numa resposta S3L ao originador. Valores de retorno:
A func~ao retorna, se bem sucedida, o numero de bytes dos dados do utiliza- dor integrados na mensagem S3L (esse numero n~ao tem qualquer relac~ao com o par^ametro count). Caso contrario retorna -1 e errno e modi cada de acordo
com o erro espec co em causa.
Erros: Os mesmos valores produzidos por read e getsockopt e mais alguns valores
espec cos:
EINVAL:
ctxnulo; EPROTO:
a leitura da mensagem S3L completa falhou ou a sua desassemblagem falhou;
Ver tambem:
read,S3Lwrite
Nome: S3Lrecv, S3Lrecvfrom, S3Lrecvmsg { le^em mensagens S3L de um descritor
de S3Lrecv
socket S3Lrecvfrom
S3Lrecvmsg
Sinopse:
#include <s3lsocket.h>
int S3Lrecv (int fd, char *buf, int len, unsigned int flags, S3LCtx *ctx);
int S3Lrecvfrom (int fd, char *buf, int len, unsigned int flags, struct sockaddr *from, int *fromlen, void *ctx);
int S3Lrecvmsg (int fd, struct msghdr *msg, unsigned int flags, S3LCtx *ctx);
Descric~ao:
As func~oesS3LrecveS3Lrecvfroms~ao semelhantes as func~oesrecve recvfrom,
excepto que embufs~ao colocados os dados do utilizador integrados na mensagem
S3L lida defd.
A func~ao S3Lrecvfrom pode ser usada para receber mensagens S3L ponto{a{
ponto ou multiponto, conforme o tipo do endereco IP relativo a origem dessas mensagens. A necessidade dessa distinc~ao implica que tal endereco seja sempre solicitado, internamente, arecvfrom, sendo devolvido para o exterior em func~ao
do valor dos camposfromefromlende S3Lrecvfrom. Internamente s~ao tambem
feitas as convers~oes adequadas de ctx para S3LCtx * ou S3LMCtx *. Note{se
ainda que a recepc~ao de mensagens S3L multiponto atraves deS3Lrecvfromesta
limitada asocketsfd de domnioAF INET e tipoSOCK DGRAM.
O par^ametrolenpermanece por raz~oes de compatibilidade de sintaxe, n~ao sendo
determinante no numero de bytes lidos, uma vez que S3Lrecv e S3Lrecvfrom
l^eem sempre uma mensagem S3L completa. Contudo, espera{se que buf tenha
pelo menos a dimens~ao dada porlen.
A func~ao S3Lrecvmsg e analoga a func~ao recvmsg excepto que o vector msg->msg iov recebe os dados produzidos pela desassemblagem, com base no
contexto ctx, de um vector de mensagens S3L.
O contexto S3L de recepc~ao e gravado emctx, permitindo, posteriormente, uma
eventual reutilizac~ao. Valores de retorno:
As func~oes retornam, se bem sucedidas, o numero de bytes dos dados do utilizador integrados na mensagem S3L ou a soma desses bytes, no caso de ter sido lido um vector (o valor de retorno n~ao tem qualquer relac~ao com o par^ametro len
ou com o valor inicial dos campos iov len do vector fornecido; estes ultimos
s~ao modi cados, re ectindo o numero de bytes recebidos em cada celula). Caso contrario retornam -1 e errnoe modi cada de acordo com o erro espec co em
causa.
Erros: Os mesmos valores produzidos porrecvfrom,recvmsg,getsockopte mais alguns
valores espec cos:
EINVAL:
ctxnulo; EPROTO:
a leitura da mensagem S3L completa (ou do vector de mensagens S3L) falhou ou a sua desassemblagem falhou;
Ver tambem:
Nome: S3Lreadv{ l^e um vector de mensagens S3L de um descritor de cheiro S3Lreadv
Sinopse:
#include <s3lsocket.h>
int S3Lreadv (int fd, struct iovec *vector, size t count, S3LCtx *ctx);
Descric~ao:
A func~ao S3Lreadv e semelhantes a func~ao readv, excepto que em vector s~ao
colocados os dados do utilizador integrados nas mensagens S3L de um vector lido defd.
Os valores originais dos camposiov lendo vectorvectorn~ao s~ao determinantes
para o numero de bytes lidos da mensagem S3L correspondente, uma vez que se l^e um vector linearizado de mensagens S3L completas. Contudo, espera{se que cadaiov basedevectortenha pelo menos a dimens~ao dada pelo campoiov len
respectivo.
O contexto S3L de recepc~ao e gravado emctx, permitindo a sua eventual reuti-
lizac~ao numa resposta S3L ao originador. Valores de retorno:
A func~ao retorna, se bem sucedida, a soma do numero de bytes depositados no vector (o valor de retorno n~ao tem qualquer relac~ao com o o valor inicial dos camposiov len do vector fornecido; estes ultimos s~ao modi cados, re ectindo o
numero de bytes recebidos em cada celula). Caso contrario retorna-1 eerrnoe
modi cada de acordo com o erro espec co em causa.
Erros: Os mesmos valores produzidos por read, readv, recvfrom, getsockopt e mais
alguns valores espec cos:
EINVAL:
ctxnulo; EPROTO:
a leitura do vector completo de mensagens S3L falhou ou a sua desas- semblagem falhou;
Ver tambem:
readv,S3Lwritev