*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->HP-UX 11i man pages -> send (2)              
Title
Content
Arch
Section
 

Contents


 send(2)                                                             send(2)




 NAME    [Toc]    [Back]
      send(), sendmsg(), sendto() - send a message from a socket

 SYNOPSIS    [Toc]    [Back]
      #include <sys/socket.h>

      int send(int s, const void *msg, int len, int flags);

      int sendto(
          int         s,
          const void *msg,
          int         len,
          int         flags,
          const void *to,
          int         tolen
      );

      int sendmsg(int s, const struct msghdr msg[], int flags);

    _XOPEN_SOURCE_EXTENDED Only (UNIX 98)
      ssize_t send(int s, const void *msg, size_t len, int flags);

      ssize_t sendto(
              int                    s,
              const void            *msg,
              size_t                 len,
              int                    flags,
              const struct sockaddr *to,
              socklen_t              tolen
      );

      ssize_t sendmsg(int s, const struct msghdr *msg, int flags);

    Obsolescent _XOPEN_SOURCE_EXTENDED Only (UNIX 95)    [Toc]    [Back]
      ssize_t sendto(
              int                    s,
              const void            *msg,
              size_t                 len,
              int                    flags,
              const struct sockaddr *to,
              size_t                 tolen
      );

 DESCRIPTION    [Toc]    [Back]
      The send(), sendmsg(), and sendto() system calls transmit a message to
      another socket.  send() can be used only when the socket is in a
      connected state, whereas sendmsg() and sendto() can be used at any
      time.  sendmsg() allows the send data to be gathered from several
      buffers specified in the msghdr structure.





 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




      s is a socket descriptor that specifies the socket on which the
      message will be sent.

      msg points to the buffer containing the message.

      If the socket uses connection-based communications, such as a
      SOCK_STREAM socket, these calls can only be used after the connection
      has been established (see connect(2)).  In this case, any destination
      specified by to is ignored.  For connectionless sockets, such as
      SOCK_DGRAM, sendto() must be used unless the destination address has
      already been specified by connect().  If the destination address has
      been specified and sendto() is used, an error results if any address
      is specified by to.

      The address of the target socket is contained in a socket address
      structure pointed to by to, with tolen specifying the size of the
      structure.

      If a sendto() is attempted on a SOCK_DGRAM socket before any local
      address has been bound to it, the system automatically selects a local
      address to be used for the message.  In this case, there is no
      guarantee that the same local address will be used for successive
      sendto() requests on the same socket.

      The length of the message is given by len in bytes.  The length of
      data actually sent is returned.  If the message is too long to pass
      atomically through the underlying protocol, the message is not
      transmitted, -1 is returned, and errno is set to [EMSGSIZE].  For
      SOCK_DGRAM sockets, this size is fixed by the implementation (see the
      DEPENDENCIES section).  Otherwise there is no size limit.

      When send() or sendto() returns a positive value, it only indicates
      this number of bytes have been sent to the local transport provider.
      It does not mean this number of bytes have been delivered to the peer
      socket application.  A SOCK_DGRAM socket does not guarantee end-to-end
      delivery.  A SOCK_STREAM socket guarantees eventual end-to-end
      delivery, however its underlying transport provider may later detect
      an irrecoverable error and returns a value of -1 at another socket
      function call.

      When send() or sendto() returns a value of -1 , it indicates a locally
      detected error.  errno is set to indicate the error.

      sendmsg() performs the same action as send(), but it gathers the
      output data from the buffers specified in the msghdr structure (see
      _XOPEN_SOURCE_EXTENDED Only below).  This structure is defined in
      <sys/socket.h> and has the following form (HP-UX BSD Sockets Only):

           struct msghdr {
               caddr_t   msg_name;            /* optional address */
               int       msg_namelen;         /* size of address  */



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




               struct    iovec *msg_iov;      /* scatter array for data */
               int       msg_iovlen;          /* # of elements in msg_iov */
               caddr_t   msg_accrights;       /* access rights */
               int       msg_accrightslen;    /* size of msg_accrights */
           }

      msg_name points to a sockaddr structure in which the address of the
      destination socket should be stored, if the socket is connectionless;
      msg_name may be a null pointer if no name is specified.  msg_iov
      specifies the locations of the character arrays for storing the
      outbound data.  msg_accrights specifies a buffer that contains any
      access rights to be sent along with the message.  Access rights are
      limited to file descriptors of size int.  If access rights are not
      being transferred, set the msg_accrights field to NULL.  Access rights
      are supported only for AF_UNIX.

      If no buffer space is available to hold the data to be transmitted,
      send() blocks unless nonblocking mode is enabled.  The three ways to
      enable nonblocking mode are:

           +  with the FIOSNBIO ioctl() request,

           +  with the O_NONBLOCK flag, and

           +  with the O_NDELAY fcntl() flag.

      If nonblocking I/O is enabled using FIOSNBIO or the equivalent FIONBIO
      request (defined in <sys/ioctl.h> and explained in ioctl(2), ioctl(5),
      and socket(7)), although the use of FIONBIO is not recommended, the
      send() request completes in one of three ways:

           +  If there is enough space available in the system to buffer all
              of the data, send() completes successfully, having written out
              all of the data, and returns the number of bytes written.

           +  If there is not enough space in the buffer to write out the
              entire request, send() completes successfully, having written
              as much data as possible, and returns the number of bytes it
              was able to write.

           +  If there is no space in the system to buffer any of the data,
              send() fails, having written no data, and errno is set to
              [EWOULDBLOCK].

      If nonblocking I/O is disabled using FIOSNBIO, send() always executes
      completely (blocking as necessary) and returns the number of bytes
      written.

      If the O_NONBLOCK flag is set using fcntl() (defined in <sys/fcntl.h>
      and explained in fcntl(2) and fcntl(5)), POSIX-style nonblocking I/O
      is enabled.  In this case, the send() request completes in one of



 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




      three ways:

           +  If there is enough space available in the system to buffer all
              of the data, send() completes successfully, having written out
              all of the data, and returns the number of bytes written.

           +  If there is not enough space in the buffer to write out the
              entire request, send() completes successfully, having written
              as much data as possible, and returns the number of bytes it
              was able to write.

           +  If there is no space in the system to buffer any of the data,
              send() completes, having written no data, and returns -1, with
              errno set to [EAGAIN].

      If the O_NDELAY flag is set using fcntl() (defined in <sys/fcntl.h>
      and explained in fcntl(2) and fcntl(5)), nonblocking I/O is enabled.
      In this case, the send() request completes in one of three ways:

           +  If there is enough space available in the system to buffer all
              of the data, send() completes successfully, having written out
              all of the data, and returns the number of bytes written.

           +  If there is not enough space in the buffer to write out the
              entire request, send() completes successfully, having written
              as much data as possible, and returns the number of bytes it
              was able to write.

           +  If there is no space in the system to buffer any of the data,
              send() completes successfully, having written no data, and
              returns 0.

      If the O_NDELAY flag is cleared using fcntl(), nonblocking I/O is
      disabled.  In this case, the send() always executes completely
      (blocking as necessary) and returns the number of bytes written.

      Since the fcntl() O_NONBLOCK and O_NDELAY flags and ioctl() FIOSNBIO
      requests are supported, the following clarifies on how these features
      interact.  If the O_NONBLOCK or O_NDELAY flag has been set, send()
      requests behave accordingly, regardless of any FIOSNBIO requests.  If
      neither the O_NONBLOCK flag nor the O_NDELAY flag has been set,
      FIOSNBIO requests control the behavior of send().

      By default nonblocking I/O is disabled.

      The supported values for flags are zero or MSG_OOB (to send out-ofband
 data).  A write() call made to a socket behaves in exactly the
      same way as send() with flags set to zero.  MSG_OOB is not supported
      for AF_UNIX or AF_VME_LINK sockets.





 Hewlett-Packard Company            - 4 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




      select(2) can be used to determine when it is possible to send more
      data.

    AF_CCITT Only    [Toc]    [Back]
      Sockets of the address family AF_CCITT operate in message mode.
      Although they are specified as connection-based (SOCK_STREAM) sockets,
      the X.25 subsystem communicates via messages.  They require that a
      connection be established with the connect() or accept() calls.

      The O_NDELAY flag is not supported.  Use FIOSNBIO requests to control
      nonblocking I/O.  If the available buffer space is not large enough
      for the entire message and the socket is in nonblocking mode, errno is
      set to [EWOULDBLOCK].  If the amount of data in the send() exceeds the
      maximum outbound message size, errno is set to [EMSGSIZE].

      The sendto() call is not supported.

      Each call sends either a complete or a partial X.25 message.  This is
      controlled by the setting of the More-Data-To-Follow (MDTF) bit.  If
      the user wants to send a partial message, MDTF should be set to 1
      before the send() call.  The MDTF bit should be cleared to 0 before
      sending the final message fragment.

      Message fragment length may range from 0 bytes up to the size of the
      socket's send buffer.  The MDTF bit and multiple send() calls can be
      combined to transmit complete X.25 packet sequences (i.e., zero or
      more DATA packets in which the More Data bit is set, followed by one
      DATA packet in which the More Data bit is clear) of arbitrary length.
      Note that a 0-byte message is not actually sent, but may be necessary
      to flush a complete X.25 message if the user is controlling the MDTF
      bit.

      Sockets of the AF_CCITT address family can send 1 byte of out-of-band
      data (known as an INTERRUPT data packet in X.25 terminology), or up to
      32 bytes if the X.25 interface is configured for 1984 CCITT X.25
      recommendations.  INTERRUPT data packets sent in blocking mode cause
      the process to block until confirmation is received.  INTERRUPT data
      packets sent with the socket in nonblocking mode do not cause the
      process to block; instead, an out-of-band message is queued to the
      socket when the INTERRUPT confirmation packet is received (see
      recv(2)).

    _XOPEN_SOURCE_EXTENDED Only
      For X/Open Sockets, the msghdr structure has the following form:

           (UNIX 98)

           struct msghdr {
               void       *msg_name;           /* optional address */
               socklen_t   msg_namelen;        /* size of address  */
               struct      iovec *msg_iov;     /* scatter array for data */



 Hewlett-Packard Company            - 5 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




               int         msg_iovlen;         /* # of elements in msg_iov */
               void       *msg_control;        /* ancillary data, see below */
               socklen_t   msg_controllen;     /* ancillary data buffer len */
               int         msg_flags;          /* flags on received message */
           }

           Obsolescent (UNIX 95)    [Toc]    [Back]

           struct msghdr {
               void       *msg_name;           /* optional address */
               size_t      msg_namelen;        /* size of address  */
               struct      iovec *msg_iov;     /* scatter array for data */
               int         msg_iovlen;         /* # of elements in msg_iov */
               void       *msg_control;        /* ancillary data, see below */
               size_t      msg_controllen;     /* ancillary data buffer len */
               int         msg_flags;          /* flags on received message */
           }

      msg_control specifies a buffer of ancillary data to send along with
      the message.  Ancillary data consists of a sequence of pairs, each
      consisting of a cmsghdr structure followed by a data array.  The data
      array contains the ancillary data message, and the cmsghdr structure
      contains descriptive information that allows an application to
      correctly parse the data.  cmsghdr has the following structure:

           (UNIX 98)

           struct cmsghdr {
               socklen_t  cmsg_len;      /* data byte count, including hdr*/
               int        cmsg_level;    /* originating protocol */
               int        cmsg_type;     /* protocol-specific type */
           }

           Obsolescent (UNIX 95)    [Toc]    [Back]

           struct cmsghdr {
               size_t     cmsg_len;      /* data byte count, including hdr*/
               int        cmsg_level;    /* originating protocol */
               int        cmsg_type;     /* protocol-specific type */
           }

      If the cmsg_level is SOL_SOCKET, and cmsg_type is SCM_RIGHTS, then it
      indicates that the data array contains the access rights to be sent.
      Access rights are supported only for AF_UNIX.  Access rights are
      limited to file descriptors of size int.

      If the cmsg_level is IPPROTO_IPV6, then cmsg_type must be one of the
      supported types: IPV6_PKTINFO, IPV6_HOPLIMIT, IPV6_NEXTHOP,
      IPV6_RTHDR, IPV6_HOPOPTS, IPV6_DSTOPTS or IPV6_RTHDRDSTOPTS.  (See
      description in ip6(7P)).




 Hewlett-Packard Company            - 6 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




      If ancillary data are not being transferred, set the msg_control field
      to NULL, and set the msg_controllen field to 0.

      The msg_flags member is ignored.

 RETURN VALUE    [Toc]    [Back]
      send(), sendmsg(), and sendto() return the following values:

            n   Successful completion.  n is the number of bytes sent.
           -1   Failure.  errno is set to indicate the error.

 ERRORS    [Toc]    [Back]
      If send(), sendmsg(), or sendto() fails, errno is set to one of the
      following values.

           [EACCES]            Process doing a send() of a broadcast packet
                               does not have broadcast capability enabled
                               for the socket.  Use setsockopt() to enable
                               broadcast capability.

           [EAFNOSUPPORT]      The specified address is not a valid address
                               for the address family of this socket.

           [EAGAIN]            Nonblocking I/O is enabled using the
                               O_NONBLOCK flag with fcntl(), and the
                               requested operation would block, or the
                               socket has an error that was set
                               asynchronously.  An asynchronous error can be
                               caused by a gateway failing to forward a
                               datagram from this socket because the
                               datagram exceeds the MTU of the next-hop
                               network and the "Don't Fragment" (DF) bit in
                               the datagram is set.  (See SO_PMTU in
                               getsockopt(2)).

           [EBADF]             s is not a valid file descriptor.

           [ECONNRESET]        A connection was forcibly closed by a peer.

           [EDESTADDRREQ]      The to parameter needs to specify a
                               destination address for the message.  This is
                               also given if the specified address contains
                               unspecified fields (see inet(7F)).

           [EFAULT]            An invalid pointer was specified in the msg
                               or to parameter, or in the msghdr structure.

           [EINTR]             The operation was interrupted by a signal
                               before any data was sent.  (If some data was
                               sent, send() returns the number of bytes sent
                               before the signal, and [EINTR] is not set).



 Hewlett-Packard Company            - 7 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




           [EINVAL]            The len or tolen parameter, or a length in
                               the msghdr structure is invalid.  A sendto()
                               system call was issued on an X.25 socket, or
                               the connection is in its reset sequence and
                               cannot accept data.

           [EIO]               A timeout occurred.

           [EISCONN]           An address was specified by to for a
                               SOCK_DGRAM socket which is already connected.

           [EMSGSIZE]          A length in the msghdr structure is invalid.
                               The socket requires that messages be sent
                               atomically, and the size of the message to be
                               sent made this impossible.

                               SOCK_DGRAM/AF_INET or SOCK_STREAM/AF_CCITT:
                               The message size exceeded the outbound buffer
                               size.

           [ENETDOWN]          The interface used for the specified address
                               is "down" (see ifconfig(1M)), no interface
                               for the specified address can be found
                               (SO_DONTROUTE socket option in use), or the
                               X.25 Level 2 is down.

           [EHOSTUNREACH]      The destination host is not reachable.

           [ENETUNREACH]       The destination network is not reachable.
                               Some of the possible causes for this error
                               are:

                               (LAN) All encapsulations (e.g., ether, ieee)
                               have been turned off (see also ifconfig(1M)).

                               (X.25) The X.25 Level 2 is down.  The X.25
                               link layer is not working (wires might be
                               broken, connections are loose on the
                               interface hoods at the modem, the modem
                               failed, the packet switch at the remote end
                               lost power or failed for some reason, or
                               electrical noise interfered with the line for
                               an extremely long period of time).

           [ENOBUFS]           No buffer space is available in the system to
                               perform the operation.

           [ENOMEM]            No memory is available in the system to
                               perform the operation.





 Hewlett-Packard Company            - 8 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




           [ENOPROTOOPT]       The remote system or an intermediate system
                               in the communications path does not support a
                               protocol option sent by the local system.
                               This option may have been set using a
                               getsockopt() or setsockopt() call, or set as
                               a system parameter.

           [ENOTCONN]          A send() on a socket that is not connected,
                               or a send() on a socket that has not
                               completed the connect sequence with its peer,
                               or is no longer connected to its peer.

           [ENOTSOCK]          s is a valid file descriptor, but it is not a
                               socket.

           [EOPNOTSUPP]        The MSG_OOB flag was specified; it is not
                               supported for AF_UNIX or AF_VME_LINK sockets.

           [EPIPE] and SIGPIPE signal
                               An attempt was made to send on a socket that
                               was connected, but the connection has been
                               shut down either by the remote peer or by
                               this side of the connection.  Note that the
                               default action for SIGPIPE, unless the
                               process has established a signal handler for
                               this signal, is to terminate the process.

           [EWOULDBLOCK]       Nonblocking I/O is enabled using ioctl()
                               FIOSNBIO request and the requested operation
                               would block.

 WARNINGS    [Toc]    [Back]
      IPv6 is supported on HP-UX 11i Version 1.0, with the optional IPv6
      software installed.  Currently, IPv6 is not supported on systems
      running HP-UX 11i Version 1.6.

 DEPENDENCIES    [Toc]    [Back]
      UDP messages are fragmented at the IP level into Maximum Transmission
      Unit (MTU) sized pieces; MTU varies for different link types.  These
      pieces, called IP fragments, can be transmitted, but IP does not
      guarantee delivery.  Sending large messages may cause too many
      fragments and overrun a receiver's ability to receive them.  If this
      happens the complete message cannot be reassembled.  This affects the
      apparent reliability and throughput of the network as viewed by the
      end user.

      The default and maximum buffer sizes are protocol-specific.  Refer to
      the appropriate entries in Sections 7F and 7P for details.  The buffer
      size can be set by calling setsockopt() with SO_SNDBUF.





 Hewlett-Packard Company            - 9 -   HP-UX 11i Version 2: August 2003






 send(2)                                                             send(2)




    AF_CCITT    [Toc]    [Back]
      If the receiving process is on a Series 700/800 HP-UX system, and the
      connection has been set up to use the D-bit, data sent with the D-bit
      set is acknowledged when the receiving process has read the data.
      Otherwise, the acknowledgement is sent when the firmware receives it.

 OBSOLESCENCE    [Toc]    [Back]
      Currently, the socklen_t and size_t types are the same size.  This is
      compatible with both the UNIX 95 and UNIX 98 profiles.  However, in a
      future release, socklen_t might be a different size.  In that case,
      the size of the msghdr and cmsghdr structures and the relative
      position of their members will be different, which might affect
      application behavior.  Applications that use socklen_t now, where
      appropriate, will avoid such migration problems.  On the other hand,
      applications that need to be portable to the UNIX 95 profile should
      follow the X/Open specification (see xopen_networking(7)).

 FUTURE DIRECTION    [Toc]    [Back]
      Currently, the default behavior is the HP-UX BSD Sockets; however, it
      might be changed to X/Open Sockets in a future release.  At that time,
      any HP-UX BSD Sockets behavior that is incompatible with X/Open
      Sockets might be obsoleted.  Applications that conform to the X/Open
      specification now will avoid migration problems (see
      xopen_networking(7)).

 AUTHOR    [Toc]    [Back]
      send(), sendmsg(), and sendto() were developed by HP and the
      University of California, Berkeley.

 SEE ALSO    [Toc]    [Back]
      ifconfig(1M), getsockopt(2), recv(2), select(2), setsockopt(2),
      socket(2), thread_safety(5), socket(7), inet(7F), tcp(7P), udp(7P),
      ip6(7P), unix(7P), xopen_networking(7).

 STANDARDS CONFORMANCE    [Toc]    [Back]
      send(): XPG4


 Hewlett-Packard Company           - 10 -   HP-UX 11i Version 2: August 2003
[ Back ]
      
      
 Similar pages
Name OS Title
sendmsg Tru64 Send a message from a socket using a message structure
send Tru64 Send messages on a socket
sendfile FreeBSD send a file to a socket
sendto Tru64 Send messages through a socket
sendfile HP-UX send the contents of a file through a socket
sendfile Tru64 Send the contents of a file through a socket
shutdown Tru64 Shut down socket send and receive operations
sendfile64 HP-UX send the contents of a Large File through a socket
recvmsg Tru64 Receive a message from a socket using a message structure
send Tru64 send a message (only available within the message handling system, mh)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service