Return to recv.2 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man2

Annotation of 43BSDTahoe/man/man2/recv.2, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)recv.2      6.5 (Berkeley) 7/21/87
        !             6: .\"
        !             7: .TH RECV 2 "July 21, 1987"
        !             8: .UC 5
        !             9: .SH NAME
        !            10: recv, recvfrom, recvmsg \- receive a message from a socket
        !            11: .SH SYNOPSIS
        !            12: .nf
        !            13: .ft B
        !            14: #include <sys/types.h>
        !            15: #include <sys/socket.h>
        !            16: .PP
        !            17: .ft B
        !            18: cc = recv(s, buf, len, flags)
        !            19: int cc, s;
        !            20: char *buf;
        !            21: int len, flags;
        !            22: .PP
        !            23: .ft B
        !            24: cc = recvfrom(s, buf, len, flags, from, fromlen)
        !            25: int cc, s;
        !            26: char *buf;
        !            27: int len, flags;
        !            28: struct sockaddr *from;
        !            29: int *fromlen;
        !            30: .PP
        !            31: .ft B
        !            32: cc = recvmsg(s, msg, flags)
        !            33: int cc, s;
        !            34: struct msghdr *msg;
        !            35: int flags;
        !            36: .ft R
        !            37: .SH DESCRIPTION
        !            38: .IR Recv ,
        !            39: .IR recvfrom ,
        !            40: and
        !            41: .IR recvmsg
        !            42: are used to receive messages from a socket.
        !            43: .PP
        !            44: The 
        !            45: .I recv
        !            46: call is normally used only on a 
        !            47: .I connected
        !            48: socket (see
        !            49: .IR connect (2)),
        !            50: while 
        !            51: .I recvfrom
        !            52: and 
        !            53: .I recvmsg
        !            54: may be used to receive data on a socket whether
        !            55: it is in a connected state or not.
        !            56: .PP
        !            57: If
        !            58: .I from
        !            59: is non-zero, the source address of the message is filled in.
        !            60: .I Fromlen
        !            61: is a value-result parameter, initialized to the size of
        !            62: the buffer associated with
        !            63: .IR from ,
        !            64: and modified on return to indicate the actual size of the
        !            65: address stored there.
        !            66: The length of the message is returned in
        !            67: .IR cc .
        !            68: If a message is too long to fit in the supplied buffer,
        !            69: excess bytes may be discarded depending on the type of socket
        !            70: the message is received from (see
        !            71: .IR socket (2)).
        !            72: .PP
        !            73: If no messages are available at the socket, the
        !            74: receive call waits for a message to arrive, unless
        !            75: the socket is nonblocking (see
        !            76: .IR ioctl (2))
        !            77: in which case a
        !            78: .I cc
        !            79: of \-1 is returned with the external variable errno
        !            80: set to EWOULDBLOCK.
        !            81: .PP
        !            82: The
        !            83: .IR select (2)
        !            84: call may be used to determine when more data arrives.
        !            85: .PP
        !            86: The
        !            87: .I flags
        !            88: argument to a recv call is formed by 
        !            89: .IR or 'ing
        !            90: one or more of the values,
        !            91: .PP
        !            92: .nf
        !            93: .RS
        !            94: .ta \w'#define\ \ 'u +\w'MSG_DONTROUTE\ \ \ 'u +\w'0x\0\0\0\ \ 'u
        !            95: #define        MSG_OOB 0x1     /* process out-of-band data */
        !            96: #define        MSG_PEEK        0x2     /* peek at incoming message */
        !            97: .RE
        !            98: .fi
        !            99: .PP
        !           100: The
        !           101: .I recvmsg
        !           102: call uses a 
        !           103: .I msghdr
        !           104: structure to minimize the number of directly supplied parameters.
        !           105: This structure has the following form, as defined in
        !           106: .IR <sys/socket.h> :
        !           107: .PP
        !           108: .nf
        !           109: .RS
        !           110: .DT
        !           111: struct msghdr {
        !           112:        caddr_t msg_name;               /* optional address */
        !           113:        int     msg_namelen;            /* size of address */
        !           114:        struct  iovec *msg_iov;         /* scatter/gather array */
        !           115:        int     msg_iovlen;             /* # elements in msg_iov */
        !           116:        caddr_t msg_accrights;          /* access rights sent/received */
        !           117:        int     msg_accrightslen;
        !           118: };
        !           119: .RE
        !           120: .fi
        !           121: .PP
        !           122: Here
        !           123: .I msg_name
        !           124: and
        !           125: .I msg_namelen
        !           126: specify the destination address if the socket is unconnected;
        !           127: .I msg_name
        !           128: may be given as a null pointer if no names are desired or required.
        !           129: The 
        !           130: .I msg_iov
        !           131: and
        !           132: .I msg_iovlen
        !           133: describe the scatter gather locations, as described in
        !           134: .IR read (2).
        !           135: A buffer to receive any access rights sent along with the message is specified
        !           136: in 
        !           137: .IR msg_accrights ,
        !           138: which has length
        !           139: .IR msg_accrightslen .
        !           140: Access rights are currently limited to file descriptors,
        !           141: which each occupy the size of an
        !           142: .BR int .
        !           143: If access rights are not being transferred, the 
        !           144: .I msg_accrights
        !           145: field should be set to NULL.
        !           146: .SH "RETURN VALUE
        !           147: These calls return the number of bytes received, or \-1
        !           148: if an error occurred.
        !           149: .SH ERRORS
        !           150: The calls fail if:
        !           151: .TP 20
        !           152: [EBADF]
        !           153: The argument \fIs\fP is an invalid descriptor.
        !           154: .TP 20
        !           155: [ENOTSOCK]
        !           156: The argument \fIs\fP is not a socket.
        !           157: .TP 20
        !           158: [EWOULDBLOCK]
        !           159: The socket is marked non-blocking and the receive operation
        !           160: would block.
        !           161: .TP 20
        !           162: [EINTR]
        !           163: The receive was interrupted by delivery of a signal before
        !           164: any data was available for the receive.
        !           165: .TP 20
        !           166: [EFAULT]
        !           167: The data was specified to be received into a non-existent
        !           168: or protected part of the process address space.
        !           169: .SH SEE ALSO
        !           170: fcntl(2), read(2), send(2), select(2), getsockopt(2), socket(2)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.