Commit | Line | Data |
---|---|---|
3f6f0ccf KB |
1 | .\" Copyright (c) 1983, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
7611a06d | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
da268306 | 5 | .\" |
3f6f0ccf | 6 | .\" @(#)send.2 8.1 (Berkeley) %G% |
7611a06d | 7 | .\" |
931b8415 CL |
8 | .Dd |
9 | .Dt SEND 2 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm send , | |
13 | .Nm sendto , | |
14 | .Nm sendmsg | |
15 | .Nd send a message from a socket | |
16 | .Sh SYNOPSIS | |
17 | .Fd #include <sys/types.h> | |
18 | .Fd #include <sys/socket.h> | |
19 | .Ft int | |
9aae6d59 | 20 | .Fn send "int s" "const void *msg" "int len" "int flags" |
931b8415 | 21 | .Ft int |
9aae6d59 | 22 | .Fn sendto "int s" "const void *msg" "int len" "int flags" "const struct sockaddr *to" "int tolen" |
931b8415 CL |
23 | .Ft int |
24 | .Fn sendmsg "int s" "const struct msghdr *msg" "int flags" | |
25 | .Sh DESCRIPTION | |
26 | .Fn Send , | |
27 | .Fn sendto , | |
7611a06d | 28 | and |
931b8415 | 29 | .Fn sendmsg |
7611a06d | 30 | are used to transmit a message to another socket. |
931b8415 | 31 | .Fn Send |
7611a06d | 32 | may be used only when the socket is in a |
931b8415 | 33 | .Em connected |
7611a06d | 34 | state, while |
931b8415 | 35 | .Fn sendto |
7611a06d | 36 | and |
931b8415 | 37 | .Fn sendmsg |
7611a06d | 38 | may be used at any time. |
931b8415 | 39 | .Pp |
7611a06d | 40 | The address of the target is given by |
931b8415 | 41 | .Fa to |
7611a06d | 42 | with |
931b8415 | 43 | .Fa tolen |
7611a06d KM |
44 | specifying its size. |
45 | The length of the message is given by | |
931b8415 | 46 | .Fa len . |
7611a06d | 47 | If the message is too long to pass atomically through the |
931b8415 CL |
48 | underlying protocol, the error |
49 | .Er EMSGSIZE | |
50 | is returned, and | |
7611a06d | 51 | the message is not transmitted. |
931b8415 | 52 | .Pp |
7611a06d | 53 | No indication of failure to deliver is implicit in a |
931b8415 CL |
54 | .Fn send . |
55 | Locally detected errors are indicated by a return value of -1. | |
56 | .Pp | |
7611a06d KM |
57 | If no messages space is available at the socket to hold |
58 | the message to be transmitted, then | |
931b8415 | 59 | .Fn send |
7611a06d | 60 | normally blocks, unless the socket has been placed in |
def9d0f9 | 61 | non-blocking I/O mode. |
7611a06d | 62 | The |
931b8415 | 63 | .Xr select 2 |
7611a06d KM |
64 | call may be used to determine when it is possible to |
65 | send more data. | |
931b8415 | 66 | .Pp |
7611a06d | 67 | The |
931b8415 | 68 | .Fa flags |
def9d0f9 | 69 | parameter may include one or more of the following: |
931b8415 | 70 | .Bd -literal |
8a9f7379 CL |
71 | #define MSG_OOB 0x1 /* process out-of-band data */ |
72 | #define MSG_DONTROUTE 0x4 /* bypass routing, use direct interface */ | |
931b8415 CL |
73 | .Ed |
74 | .Pp | |
75 | The flag | |
76 | .Dv MSG_OOB | |
77 | is used to send | |
78 | .Dq out-of-band | |
79 | data on sockets that support this notion (e.g. | |
80 | .Dv SOCK_STREAM ) ; | |
81 | the underlying protocol must also support | |
82 | .Dq out-of-band | |
83 | data. | |
84 | .Dv MSG_DONTROUTE | |
85 | is usually used only by diagnostic or routing programs. | |
86 | .Pp | |
7611a06d | 87 | See |
931b8415 | 88 | .Xr recv 2 |
7611a06d | 89 | for a description of the |
931b8415 | 90 | .Fa msghdr |
7611a06d | 91 | structure. |
931b8415 CL |
92 | .Sh RETURN VALUES |
93 | The call returns the number of characters sent, or -1 | |
7611a06d | 94 | if an error occurred. |
931b8415 CL |
95 | .Sh ERRORS |
96 | .Fn Send , | |
97 | .Fn sendto , | |
98 | and | |
99 | .Fn sendmsg | |
100 | fail if: | |
3a2b8980 | 101 | .Bl -tag -width [EMSGSIZE] |
931b8415 | 102 | .It Bq Er EBADF |
7611a06d | 103 | An invalid descriptor was specified. |
931b8415 CL |
104 | .It Bq Er ENOTSOCK |
105 | The argument | |
106 | .Fa s | |
107 | is not a socket. | |
108 | .It Bq Er EFAULT | |
7611a06d | 109 | An invalid user space address was specified for a parameter. |
931b8415 | 110 | .It Bq Er EMSGSIZE |
7611a06d KM |
111 | The socket requires that message be sent atomically, |
112 | and the size of the message to be sent made this impossible. | |
3a2b8980 | 113 | .It Bq Er EAGAIN |
7611a06d KM |
114 | The socket is marked non-blocking and the requested operation |
115 | would block. | |
931b8415 | 116 | .It Bq Er ENOBUFS |
def9d0f9 MK |
117 | The system was unable to allocate an internal buffer. |
118 | The operation may succeed when buffers become available. | |
931b8415 | 119 | .It Bq Er ENOBUFS |
def9d0f9 MK |
120 | The output queue for a network interface was full. |
121 | This generally indicates that the interface has stopped sending, | |
122 | but may be caused by transient congestion. | |
931b8415 CL |
123 | .El |
124 | .Sh SEE ALSO | |
125 | .Xr fcntl 2 , | |
126 | .Xr recv 2 , | |
127 | .Xr select 2 , | |
128 | .Xr getsockopt 2 , | |
129 | .Xr socket 2 , | |
130 | .Xr write 2 | |
131 | .Sh HISTORY | |
132 | The | |
133 | .Nm | |
134 | function call appeared in | |
135 | .Bx 4.2 . |