.\" Copyright (c) 1983, 1990, 1991 The Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Id: recv.2,v 1.4 2005/05/30 07:34:00 juan.piernas Exp $ .\" .\" Modified Sat Jul 24 00:22:20 1993 by Rik Faith .\" Modified Tue Oct 22 17:45:19 1996 by Eric S. Raymond .\" Translated into Spanish Sat Jan 24 1998 by .\" Gerardo Aburruzaga García .\" Modified 1998,1999 by Andi Kleen .\" 2001-06-19 corrected SO_EE_OFFENDER, bug report by James Hawtin .\" Translation revised Tue Apr 6 1999 by Juan Piernas .\" Translation revised Sun Jun 27 1999 by Juan Piernas .\" Translation revised Mon Jan 17 2000 by Juan Piernas .\" Revisado por Miguel Pérez Ibars el 6-noviembre-2004 .\" .TH RECV 2 "31 diciembre 2002" "Página man de Linux" "Manual del Programador de Linux" .SH NOMBRE recv, recvfrom, recvmsg \- reciben un mensaje desde un conector .SH SINOPSIS .\" .B #include .\" .br .B #include .br .B #include .sp .BI "ssize_t recv(int " s ", void *" buf ", size_t " lon ", int " flags ); .sp .BI "ssize_t recvfrom(int " s ", void *" buf ", size_t " lon ", int " flags "," .BI "struct sockaddr *" desde ", socklen_t *" londesde ); .sp .BI "ssize_t recvmsg(int " s ", struct msghdr *" msg ", int " flags ); .SH DESCRIPCIÓN Las llamadas .B recvfrom y .B recvmsg se emplean para recibir mensajes desde un conector (``socket''), y pueden utilizarse para recibir datos de un conector sea orientado a conexión o no. .PP Si .I desde no es NULL y el conector no es orientado a conexión, la dirección fuente del mensaje se llena. El argumento .I londesde es un parámetro por referencia, inicializado al tamaño del búfer asociado con .IR desde , y modificado cuando la función regresa para indicar el tamaño real de la dirección guardada ahí. .PP La llamada a .B recv se utiliza normalmente sólo en un conector .I conectado (vea .BR connect (2)) y es idéntica a .B recvfrom con un parámetro .I desde con valor NULL. .PP Las tres rutinas devuelven la longitud del mensaje cuando terminan bien. Si un mensaje es demasiado largo como para caber en el búfer suministrado, los bytes que sobran pueden descartarse dependiendo del tipo de conector del que se reciba el mensaje (vea .BR socket (2)). .PP Si no hay mensajes disponibles en el conector, las llamadas de recepción esperan que llegue un mensaje, a menos que el conector sea no bloqueante (vea .BR fcntl (2)) en cuyo caso se devuelve el valor \-1 y la variable externa .I errno toma el valor .BR EAGAIN . Las llamadas de recepción devuelven normalmente cualquier dato disponible, hasta la cantidad pedida, en vez de esperar la recepción de la cantidad pedida completa. .PP Las llamadas .BR select (2) o .BR poll (2) pueden emplearse para determinar cuándo llegan más datos. .PP El argumento .I flags de una llamada a recv se forma aplicando el operador de bits .IR O -lógico a uno o más de los valores siguientes: .TP .B MSG_OOB Esta opción pide la recepción de datos fuera-de-banda que no se recibirían en el flujo de datos normal. Algunos protocolos ponen datos despachados con prontitud en la cabeza de la cola de datos normales, y así, esta opción no puede emplearse con tales protocolos. .TP .B MSG_PEEK Esta opción hace que la operación de recepción devuelva datos del principio de la cola de recepción sin quitarlos de allí. Así, una próxima llamada de recepción devolverá los mismos datos. .TP .B MSG_WAITALL Esta opción hace que la operación se bloquee hasta que se satisfaga la petición completamente. Sin embargo, la llamada puede aún devolver menos datos de los pedidos si se captura una señal, si ocurre un error o una desconexión, o si los próximos datos que se van a recibir son de un tipo diferente del que se ha devuelto. .TP .B MSG_NOSIGNAL Esta opción desactiva el que se produzca una señal .B SIGPIPE sobre los conectores orientados a conexión cuando el otro extremo desaparece. .TP .B MSG_TRUNC Devuelve la longitud real del paquete, incluso cuando es más largo que el búfer pasado. Esta opción sólo es válida para conectores de paquete. .TP .B MSG_ERRQUEUE Esta opción indica que los errores encolados deben recibirse desde la cola de errores de conectores. El error se pasa en un mensaje auxiliar con un tipo dependiente del protocolo (para IPv4 éste es .BR IP_RECVERR ). El usuario debe proporciona un buffer de tamaño suficiente. Vea .BR cmsg (3) y .BR ip (7) para obtener más información. El contenido útil del paquete original que provocó el error se pasa como datos normales a través de .BR msg_iovec . La dirección original de destino del datagrama que provocó el error se pasa a través de .BR msg_name . .IP Para errores locales, no se pasa ninguna dirección (ésto puede comprobarse con el miembro .I cmsg_len de .BR cmsghdr ). Para los errores recibidos, se asigna .B MSG_ERRQUEUE a .BR msghdr . Después de que se haya pasado un error, el error de conector pendiente se regenera basándose en el siguiente error encolado y se pasará en la siguiente operación de conectores. El error se suministra en una estructura .BR sock_extended_err : .IP .RS .ne 18 .nf .ta 4n 20n 32n #define SO_EE_ORIGIN_NONE 0 #define SO_EE_ORIGIN_LOCAL 1 #define SO_EE_ORIGIN_ICMP 2 #define SO_EE_ORIGIN_ICMP6 3 struct sock_extended_err { u_int32_t ee_errno; /* número de error */ u_int8_t ee_origin; /* origen del error */ u_int8_t ee_type; /* tipo */ u_int8_t ee_code; /* código */ u_int8_t ee_pad; u_int32_t ee_info; /* información adicional */ u_int32_t ee_data; /* otros datos */ /* Pueden ir más datos a continuación .*/ }; struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *); .ta .fi .RE .IP .B ee_errno contiene el número errno del error encolado. .B ee_origin es el código del origen en donde se ha originado el error. Los otros campos son específicos del protocolo. La macro .B SOCK_EE_OFFENDER devuelve un puntero a la dirección del objeto de red desde donde se ha originado el error dando un puntero al mensaje auxiliar. Si esta dirección se desconoce, el miembro .I sa_family de .B sockaddr contiene .B AF_UNSPEC y los otros campos de .B sockaddr quedan indefinidos. El contenido útil del paquete que ha producido el error se pasa como datos normales. .IP Para los errores locales no se pasa ninguna dirección (esto se puede comprobar con el miembro .I cmsg_len de .BR cmsghdr ). Para los errores recibidos, se asigna .B MSG_ERRQUEUE a .BR msghdr . Después de que se haya pasado un error, el error de conector pendiente se regenera basándose en el siguiente error encolado y se pasará en la siguiente operación de conectores. .PP La llamada .B recvmsg utiliza una estructura .I msghdr para minimizar el número de parámetros suministrados directamente. Esta estructura tiene la forma siguiente, según se define en .IR : .IP .RS .nf .ta 4n 17n 33n struct msghdr { void * msg_name; /* dirección opcional */ socklen_t msg_namelen; /* tamaño de la dirección */ struct iovec * msg_iov; /* vector dispersar/agrupar */ size_t msg_iovlen; /* nº de elementos en msg_iov */ void * msg_control; /* datos auxiliares, ver más abajo */ socklen_t msg_controllen; /* long buffer datos auxiliares */ int msg_flags; /* opciones en mensaje recibido */ }; .ta .fi .RE .PP Aquí .I msg_name y .I msg_namelen especifican la dirección de origen si el conector está desconectado; .I msg_name puede darse como un puntero nulo si no se desean o requieren nombres. Los campos .I msg_iov y .I msg_iovlen describen localizaciones dispersar/agrupar, como se discute en .BR readv (2). El campo .IR msg_control , que tiene de longitud .IR msg_controllen , apunta a un búfer para otros mensajes relacionados con control de protocolo o para datos auxiliares diversos. Cuando se llama a .BR recvmsg , .I msg_controllen debe contener la longitud del buffer disponible en .IR msg_control ; a la vuelta de una llamada con éxito contendrá la longitud de la secuencia de mensajes de control. .PP Los mensajes son de la forma: .PP .RS .nf .ta 4n 16n 28n struct cmsghdr { socklen_t cmsg_len; /* Nº de byte de datos, incluye cab. */ int cmsg_level; /* protocolo originante */ int cmsg_type; /* tipo específico del protocolo */ /* seguido por u_char cmsg_data[]; */ }; .ta .fi .RE .PP Los datos auxiliares sólo deberían ser accedidos mediante las macros definidas en .BR cmsg (3). .PP Como ejemplo, Linux usa este mecanismo de datos auxiliares para pasar errores ampliados, opciones IP o descriptores de fichero mediante conectores Unix. .PP El contenido del campo .I msg_flags en msghdr se establece cuando .BR recvmsg () regresa. Puede contener numerosas opciones: .TP .B MSG_EOR indica fin-de-registro; los datos devueltos completaron un registro (generalmente empleado con conectores del tipo .BR SOCK_SEQPACKET ). .TP .B MSG_TRUNC indica que la porción trasera de un datagrama ha sido descartada porque el datagrama era más grande que el búfer suministrado. .TP .B MSG_CTRUNC indica que algún dato de control ha sido descartado debido a la falta de espacio en el búfer para datos auxiliares. .TP .B MSG_OOB se devuelve para indicar que se han recibido datos despachados prontamente o fuera-de-banda. .TP .B MSG_ERRQUEUE indica que no se ha recibido ningún dato sino un error ampliado de la cola de errores de conectores. .TP .B MSG_DONTWAIT Permite operaciones no-bloqueantes; si la operación se bloqueara, se devolvería .B EAGAIN (también se puede conseguir ésto usando la opción .B O_NONBLOCK con .B F_SETFL .BR fcntl (2)). .SH "VALOR DEVUELTO" Estas llamadas devuelven el número de bytes recibidos, o bien \-1 en caso de que ocurriera un error. .SH ERRORES Estos son algunos errores estándares generados por la capa de conectores. Los modulos de los protocolos subyacentes pueden generar y devolver errores adicionales. Consulte sus páginas de manual. .TP .B EBADF El argumento .I s es un descriptor inválido. .TP .B ECONNREFUSED Un host remoto no permite la conexión de red (normalmente porque no está ejecutando el servicio solicitado). .TP .B ENOTCONN El conector está asociado con un protocolo orientado a la conexión y no ha sido conectado (vea .BR connect (2) y .BR accept (2)). .TP .B ENOTSOCK El argumento .I s no se refiere a un conector. .TP .B EAGAIN El conector está marcado como no-bloqueante, y la operación de recepción produciría un bloqueo, o se ha puesto un límite de tiempo en la recepción, que ha expirado antes de que se recibieran datos. .TP .B EINTR La recepción ha sido interrumpida por la llegada de una señal antes de que hubiera algún dato disponible. .TP .B EFAULT El puntero a búfer de recepción (o punteros) apunta afuera del espacio de direcciones del proceso. .TP .B EINVAL Se ha pasado un argumento inválido. .SH "CONFORME A" 4.4BSD (estas funciones aparecieron por primera vez en 4.2BSD). .SH NOTA Los prototipos datos anteriormente siguen a glibc2. The Single Unix Specification coincide en todo excepto en que el tipo de los valores devueltos es `ssize_t' (mientras que BSD 4.*, libc4 y libc5 tienen `int'). El argumento .I flags es un `int' en BSD 4.* pero es un `unsigned int' en libc4 y libc5. El argumento .I lon es un `int' en BSD 4.* pero es un `size_t' en libc4 y libc5. El argumento .I londesde es un `int' en BSD 4.*, libc4 y libc5. El actual `socklen_t *' fue inventado por POSIX. Vea también .BR accept (2). .SH "VÉASE TAMBIÉN" .BR fcntl (2), .BR read (2), .BR select (2), .BR getsockopt (2), .BR socket (2), .BR cmsg (3)