Return to recv.2 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man2

Annotation of cci/usr/src/man/man2/recv.2, revision 1.1

1.1     ! root        1: .TH RECV 2 "7 July 1983"
        !             2: .UC 4
        !             3: .SH NAME
        !             4: recv, recvfrom, recvmsg \- receive a message from a socket
        !             5: .SH SYNOPSIS
        !             6: .nf
        !             7: .ft B
        !             8: #include <sys/types.h>
        !             9: #include <sys/socket.h>
        !            10: .PP
        !            11: .ft B
        !            12: cc = recv(s, buf, len, flags)
        !            13: int cc, s;
        !            14: char *buf;
        !            15: int len, flags;
        !            16: .PP
        !            17: .ft B
        !            18: cc = recvfrom(s, buf, len, flags, from, fromlen)
        !            19: int cc, s;
        !            20: char *buf;
        !            21: int len, flags;
        !            22: struct sockaddr *from;
        !            23: int *fromlen;
        !            24: .PP
        !            25: .ft B
        !            26: cc = recvmsg(s, msg, flags)
        !            27: int cc, s;
        !            28: struct msghdr msg[];
        !            29: int flags;
        !            30: .ft R
        !            31: .SH DESCRIPTION
        !            32: .IR Recv ,
        !            33: .IR recvfrom ,
        !            34: and
        !            35: .IR recvmsg
        !            36: are used to receive messages from a socket.
        !            37: .PP
        !            38: The 
        !            39: .I recv
        !            40: call may be used only on a 
        !            41: .I connected
        !            42: socket (see
        !            43: .IR connect (2)),
        !            44: while 
        !            45: .I recvfrom
        !            46: and 
        !            47: .I recvmsg
        !            48: may be used to receive data on a socket whether
        !            49: it is in a connected state or not.
        !            50: .PP
        !            51: If
        !            52: .I from
        !            53: is non-zero, the source address of the message is filled in.
        !            54: .I Fromlen
        !            55: is a value-result parameter, initialized to the size of
        !            56: the buffer associated with
        !            57: .IR from ,
        !            58: and modified on return to indicate the actual size of the
        !            59: address stored there.
        !            60: The length of the message is returned in
        !            61: .IR cc .
        !            62: If a message is too long to fit in the supplied buffer,
        !            63: excess bytes may be discarded depending on the type of socket
        !            64: the message is received from; see
        !            65: .IR socket (2).
        !            66: .PP
        !            67: If no messages are available at the socket, the
        !            68: receive call waits for a message to arrive, unless
        !            69: the socket is nonblocking (see
        !            70: .IR ioctl (2))
        !            71: in which case a
        !            72: .I cc
        !            73: of \-1 is returned with the external variable errno
        !            74: set to EWOULDBLOCK.
        !            75: .PP
        !            76: The
        !            77: .IR select (2)
        !            78: call may be used to determine when more data arrives.
        !            79: .PP
        !            80: The
        !            81: .I flags
        !            82: argument to a receive call is formed by 
        !            83: .IR or 'ing
        !            84: one or more of the values,
        !            85: .PP
        !            86: .nf
        !            87: .RS
        !            88: .DT
        !            89: #define        MSG_PEEK        0x1     /* peek at incoming message */
        !            90: #define        MSG_OOB 0x2     /* process out-of-band data */
        !            91: .RE
        !            92: .fi
        !            93: .PP
        !            94: The
        !            95: .I recvmsg
        !            96: call uses a 
        !            97: .I msghdr
        !            98: structure to minimize the number of directly supplied parameters,
        !            99: and to receive file descriptors from another process (Unix domain only).
        !           100: This structure has the following form, as defined in
        !           101: .IR <sys/socket.h> :
        !           102: .PP
        !           103: .nf
        !           104: .RS
        !           105: .DT
        !           106: struct msghdr {
        !           107:        caddr_t msg_name;               /* optional address */
        !           108:        int     msg_namelen;            /* size of address */
        !           109:        struct  iov *msg_iov;           /* scatter/gather array */
        !           110:        int     msg_iovlen;             /* # elements in msg_iov */
        !           111:        caddr_t msg_accrights;          /* access rights sent/received */
        !           112:        int     msg_accrightslen;
        !           113: };
        !           114: .RE
        !           115: .fi
        !           116: .PP
        !           117: Here
        !           118: .I msg_name
        !           119: and
        !           120: .I msg_namelen
        !           121: specify the destination address if the socket is unconnected;
        !           122: .I msg_name
        !           123: may be given as a null pointer if no names are desired or required.
        !           124: The 
        !           125: .I msg_iov
        !           126: and
        !           127: .I msg_iovlen
        !           128: describe the scatter gather locations, as described in
        !           129: .IR read (2).
        !           130: Access rights to be sent along with the message are specified
        !           131: in 
        !           132: .IR msg_accrights ,
        !           133: which has length
        !           134: .IR msg_accrightslen .
        !           135: .LP
        !           136: .I RECEIVING OUT-OF-BAND DATA IN INTERNET DOMAIN
        !           137: .LP
        !           138: When out-of-band data arrives at a socket, the system could signal
        !           139: a group of processes, or a specific process, or no process at all.
        !           140: .RS
        !           141: 
        !           142: - If the socket's process group id is 
        !           143: .I positive,
        !           144: the system signals all  process in that process group.
        !           145: 
        !           146: - If the socket's process group id is
        !           147: .I negative,
        !           148: the system only signals the process whose process id is the absolute
        !           149: value of the socket's process group id.
        !           150: 
        !           151: - If the socket's process group id is 0 (the default value), 
        !           152: the system does not signal any process.
        !           153: 
        !           154: .RE
        !           155: To assign a socket process group id, use the 
        !           156: .I ioctl(2)
        !           157: system call with the command
        !           158: .I SIOCSPGRP.
        !           159: .LP
        !           160: .I RECEIVING FILE DESCRIPTORS IN UNIX DOMAIN
        !           161: .LP
        !           162: In Unix domain, process
        !           163: .I A
        !           164: can open a set of files, then send these file descriptors to process
        !           165: .I B.
        !           166: Process
        !           167: .I B
        !           168: then can read or write those files which were already opened (and
        !           169: perhaps accessible only) by 
        !           170: .I A.
        !           171: .LP
        !           172: The active process stores the file descriptors
        !           173: in the field
        !           174: .I  msg_accrights
        !           175: of the structure
        !           176: .I msghdr,
        !           177: and use the system call
        !           178: .I sendmsg(2)
        !           179: to send the descriptors. The passive process then can receive the
        !           180: descriptors via the system call
        !           181: .I recvmsg(2);
        !           182: the descriptors are returned in the field
        !           183: .I msg_accrights
        !           184: of
        !           185: .I msghdr.
        !           186: .SH "RETURN VALUE
        !           187: These calls return the number of bytes received, or \-1
        !           188: if an error occurred.
        !           189: .SH ERRORS
        !           190: The calls fail if:
        !           191: .TP 20
        !           192: [EBADF]
        !           193: The argument \fIs\fP is an invalid descriptor.
        !           194: .TP 20
        !           195: [ENOTSOCK]
        !           196: The argument \fIs\fP is not a socket.
        !           197: .TP 20
        !           198: [EWOULDBLOCK]
        !           199: The socket is marked non-blocking and the receive operation
        !           200: would block.
        !           201: .TP 20
        !           202: [EINTR]
        !           203: The receive was interrupted by delivery of a signal before
        !           204: any data was available for the receive.
        !           205: .TP 20
        !           206: [EFAULT]
        !           207: The data was specified to be received into a non-existent
        !           208: or protected part of the process address space.
        !           209: .SH SEE ALSO
        !           210: read(2), send(2), socket(2). See also bind(2) for address formats 
        !           211: in different communication domains.

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