Return to recv.2 CVS log

Up to [CSRG BSD Unix] / 43BSDReno / lib / libc / sys

Annotation of 43BSDReno/lib/libc/sys/recv.2, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983, 1990 The Regents of the University of California.
        !             2: .\" All rights reserved.
        !             3: .\"
        !             4: .\" Redistribution and use in source and binary forms are permitted
        !             5: .\" provided that: (1) source distributions retain this entire copyright
        !             6: .\" notice and comment, and (2) distributions including binaries display
        !             7: .\" the following acknowledgement:  ``This product includes software
        !             8: .\" developed by the University of California, Berkeley and its contributors''
        !             9: .\" in the documentation or other materials provided with the distribution
        !            10: .\" and in all advertising materials mentioning features or use of this
        !            11: .\" software. Neither the name of the University nor the names of its
        !            12: .\" contributors may be used to endorse or promote products derived
        !            13: .\" from this software without specific prior written permission.
        !            14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
        !            15: .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
        !            16: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
        !            17: .\"
        !            18: .\"    @(#)recv.2      6.8 (Berkeley) 5/30/90
        !            19: .\"
        !            20: .TH RECV 2 "May 30, 1990"
        !            21: .UC 5
        !            22: .SH NAME
        !            23: recv, recvfrom, recvmsg \- receive a message from a socket
        !            24: .SH SYNOPSIS
        !            25: .nf
        !            26: .ft B
        !            27: #include <sys/types.h>
        !            28: #include <sys/socket.h>
        !            29: .PP
        !            30: .ft B
        !            31: cc = recv(s, buf, len, flags)
        !            32: int cc, s;
        !            33: char *buf;
        !            34: int len, flags;
        !            35: .PP
        !            36: .ft B
        !            37: cc = recvfrom(s, buf, len, flags, from, fromlen)
        !            38: int cc, s;
        !            39: char *buf;
        !            40: int len, flags;
        !            41: struct sockaddr *from;
        !            42: int *fromlen;
        !            43: .PP
        !            44: .ft B
        !            45: cc = recvmsg(s, msg, flags)
        !            46: int cc, s;
        !            47: struct msghdr *msg;
        !            48: int flags;
        !            49: .ft R
        !            50: .SH DESCRIPTION
        !            51: .IR Recvfrom ,
        !            52: and
        !            53: .IR recvmsg
        !            54: are used to receive messages from a socket,
        !            55: and may be used to receive data on a socket whether
        !            56: it is in a connected state or not.
        !            57: .PP
        !            58: If
        !            59: .I from
        !            60: is non-zero, the source address of the message is filled in.
        !            61: .I Fromlen
        !            62: is a value-result parameter, initialized to the size of
        !            63: the buffer associated with
        !            64: .IR from ,
        !            65: and modified on return to indicate the actual size of the
        !            66: address stored there.
        !            67: .PP
        !            68: The 
        !            69: .I recv
        !            70: call is normally used only on a 
        !            71: .I connected
        !            72: socket (see
        !            73: .IR connect (2))
        !            74: and is identitical to
        !            75: .I recfrom
        !            76: with a zero-valued
        !            77: .I fromlen
        !            78: parameter.
        !            79: As it is redundant, it may not be supported in future releases.
        !            80: .PP
        !            81: The length of the message is returned in
        !            82: .IR cc .
        !            83: If a message is too long to fit in the supplied buffer,
        !            84: excess bytes may be discarded depending on the type of socket
        !            85: the message is received from (see
        !            86: .IR socket (2)).
        !            87: .PP
        !            88: If no messages are available at the socket, the
        !            89: receive call waits for a message to arrive, unless
        !            90: the socket is nonblocking (see
        !            91: .IR ioctl (2))
        !            92: in which case a
        !            93: .I cc
        !            94: of \-1 is returned with the external variable errno
        !            95: set to EWOULDBLOCK.
        !            96: .PP
        !            97: The
        !            98: .IR select (2)
        !            99: call may be used to determine when more data arrives.
        !           100: .PP
        !           101: The
        !           102: .I flags
        !           103: argument to a recv call is formed by 
        !           104: .IR or 'ing
        !           105: one or more of the values,
        !           106: .PP
        !           107: .nf
        !           108: .RS
        !           109: .ta \w'#define\ \ 'u +\w'MSG_DONTROUTE\ \ \ 'u +\w'0x\0\0\0\ \ 'u
        !           110: #define        MSG_OOB 0x1     /* process out-of-band data */
        !           111: #define        MSG_PEEK        0x2     /* peek at incoming message */
        !           112: #define        MSG_DONTROUTE   0x4     /* send without using routing tables */
        !           113: #define        MSG_EOR 0x8     /* data completes record */
        !           114: #define        MSG_TRUNC       0x10    /* data discarded before delivery */
        !           115: #define        MSG_CTRUNC      0x20    /* control data lost before delivery */
        !           116: .RE
        !           117: .fi
        !           118: .PP
        !           119: The
        !           120: .I recvmsg
        !           121: call uses a 
        !           122: .I msghdr
        !           123: structure to minimize the number of directly supplied parameters.
        !           124: This structure has the following form, as defined in
        !           125: .IR <sys/socket.h> :
        !           126: .PP
        !           127: .nf
        !           128: .ta \w'struct  'u +\w'caddr_t   'u +\w'msg_controllen    'u
        !           129: struct msghdr {
        !           130:        caddr_t msg_name;       /* optional address */
        !           131:        u_int   msg_namelen;    /* size of address */
        !           132:        struct  iovec *msg_iov; /* scatter/gather array */
        !           133:        u_int   msg_iovlen;     /* # elements in msg_iov */
        !           134:        caddr_t msg_control;    /* ancillary data, see below */
        !           135:        u_int   msg_controllen; /* ancillary data buffer len */
        !           136:        int     msg_flags;              /* flags on received message */
        !           137: };
        !           138: .fi
        !           139: .PP
        !           140: Here
        !           141: .I msg_name
        !           142: and
        !           143: .I msg_namelen
        !           144: specify the destination address if the socket is unconnected;
        !           145: .I msg_name
        !           146: may be given as a null pointer if no names are desired or required.
        !           147: The
        !           148: .I msg_iov
        !           149: and
        !           150: .I msg_iovlen
        !           151: describe the scatter gather locations, as described in
        !           152: .IR read (2).
        !           153: .IR msg_control ,
        !           154: which has length
        !           155: .IR msg_controllen .
        !           156: This is a buffer for other protocol control related messages
        !           157: or other miscellaneous ancillary data.
        !           158: The messages are of the form:
        !           159: .PP
        !           160: .nf
        !           161: .ta \w'struct  'u +\w'u_char   'u +\w'msg_controllen    'u
        !           162: struct cmsghdr {
        !           163:        u_int   cmsg_len;       /* data byte count, including hdr */
        !           164:        int     cmsg_level;     /* originating protocol */
        !           165:        int     cmsg_type;      /* protocol-specific type */
        !           166: /* followed by
        !           167:        u_char  cmsg_data[]; */
        !           168: };
        !           169: .fi
        !           170: .RE
        !           171: As an example, one could use this to learn of changes in the data-stream
        !           172: in XNS/SPP, or in ISO, to obtain user-connection-request data by requesting
        !           173: a recvmsg with no uio provided immediately after an
        !           174: .IR accept (),
        !           175: thought of here in the sense of get-next-connection-request without
        !           176: an implicit connection confirmation.
        !           177: .PP
        !           178: Open file descriptors are now passed as ancillary data for AF_UNIX
        !           179: domain sockets, with cmsg_level being SOL_SOCKET and  cmsg_type being
        !           180: SCM_RIGHTS.
        !           181: .PP
        !           182: .I msg_flags
        !           183: is set on return in a way that may include some of the same values specified
        !           184: for the flags parameter to a recv system call.
        !           185: The returned values MSG_EOR indicates end-of-record, MSG_TRUNC indicates that
        !           186: some trailing datagram data was discarded, MSG_CTRUNC indicates that some
        !           187: control data was discarded due to lack of space.
        !           188: MSG_OOB is returned to indicate that expedited data was received.
        !           189: .PP
        !           190: .SH "RETURN VALUE"
        !           191: These calls return the number of bytes received, or \-1
        !           192: if an error occurred.
        !           193: .SH ERRORS
        !           194: The calls fail if:
        !           195: .TP 20
        !           196: [EBADF]
        !           197: The argument \fIs\fP is an invalid descriptor.
        !           198: .TP 20
        !           199: [ENOTSOCK]
        !           200: The argument \fIs\fP is not a socket.
        !           201: .TP 20
        !           202: [EWOULDBLOCK]
        !           203: The socket is marked non-blocking and the receive operation
        !           204: would block.
        !           205: .TP 20
        !           206: [EINTR]
        !           207: The receive was interrupted by delivery of a signal before
        !           208: any data was available for the receive.
        !           209: .TP 20
        !           210: [EFAULT]
        !           211: The data was specified to be received into a non-existent
        !           212: or protected part of the process address space.
        !           213: .SH SEE ALSO
        !           214: 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.