send man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

send(2)								       send(2)

NAME
       send(), sendmsg(), sendto() - send a message from a socket

SYNOPSIS
   UNIX 03 Only (X/Open Sockets)
   Obsolescent UNIX 95 Only (X/Open Sockets)
DESCRIPTION
       The and system calls transmit a message to another socket.  can be used
       only when the socket is in a connected state, whereas and can  be  used
       at  any time.  allows the send data to be gathered from several buffers
       specified in the structure.

       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,  must  be  used  unless the destination address has already
       been specified by If the destination address has been specified and  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  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  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	atomi‐
       cally  through the underlying protocol, the message is not transmitted,
       is returned, and is set to For SOCK_DGRAM sockets, this size  is	 fixed
       by  the	implementation	(see the section).  Otherwise there is no size
       limit.

       When or 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  applica‐
       tion.   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 at another socket function call.

       When or returns a value of , it indicates a locally detected error.  is
       set to indicate the error.

       performs	 the  same  action  as but it gathers the output data from the
       buffers specified in the structure  (see	 below).   This	 structure  is
       defined in and has the following form

       msg_name	 points to a 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 loca‐
       tions  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,
       blocks unless nonblocking mode is enabled.  The three  ways  to	enable
       nonblocking mode are:

	 ·  with the request,

	 ·  with the flag, and

	 ·  with the flag.

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

	 ·  If	there is enough space available in the system to buffer all of
	    the data, 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, 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,
	    fails, having written no data, and is set to

       If nonblocking I/O is disabled using always executes completely (block‐
       ing as necessary) and returns the number of bytes written.

       If  the	flag  is  set  using (defined in and explained in fcntl(2) and
       fcntl(5)), POSIX-style nonblocking I/O is enabled.  In this  case,  the
       request completes in one of three ways:

	 ·  If	there is enough space available in the system to buffer all of
	    the data, 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, 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, com‐
	    pletes, having written no data, and returns −1, with set to

       If the flag is set using (defined in  and  explained  in	 fcntl(2)  and
       fcntl(5)),  nonblocking I/O is enabled.	In this case, the request com‐
       pletes in one of three ways:

	 ·  If there is enough space available in the system to buffer all  of
	    the	 data,	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,  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, com‐
	    pletes successfully, having written no data, and returns 0.

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

       Since the and flags and requests are supported, the following clarifies
       on how these features interact.	If the or flag has been set,  requests
       behave  accordingly,  regardless	 of any requests.  If neither the flag
       nor the flag has been set, requests control the behavior of

       By default nonblocking I/O is disabled.

       The supported values for flags are zero or any combination of and

       The flag is used to send out-of-band data.

       The flag is used to initiate a write-side shutdown along with the  send
       operation.   Use	 of  the flag is semantically equivalent to a followed
       immediately (if the send is successful) by a If the data send operation
       fails  then the shutdown operation is not performed.  Once this flag is
       used in a successful call, no further data may be sent on the socket.

       A call made to a socket behaves in exactly the same way as  with	 flags
       set to zero.

       is not supported for AF_UNIX or AF_VME_LINK sockets.

       can be used to determine when it is possible to send more data.

   AF_CCITT Only
       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 con‐
       nection be established with the or calls.

       The flag is not supported.  Use requests to  control  nonblocking  I/O.
       If  the	available buffer space is not large enough for the entire mes‐
       sage and the socket is in nonblocking mode, is set to If the amount  of
       data in the exceeds the maximum outbound message size, is set to

       The 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 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 calls can be  combined
       to  transmit  complete X.25 packet sequences (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 recom‐
       mendations.  INTERRUPT data packets sent in  blocking  mode  cause  the
       process	to block until confirmation is received.  INTERRUPT data pack‐
       ets 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)).

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

       msg_control specifies a buffer of ancillary data to send along with the
       message.	 Ancillary data consists of a sequence of pairs, each consist‐
       ing 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:

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

       If the cmsg_level is then cmsg_type must be one of the supported types:
       or (See description in ip6(7P)).

       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.

   X/Open Sockets Compilation Environment
       See xopen_networking(7).

RETURN VALUE
       and return the following values:

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

ERRORS
       If or fails, is set to one of the following values.

	      Process doing a	  of a broadcast packet does not  have	broad‐
				  cast capability enabled for the socket.  Use
				  to enable broadcast capability.

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

	      Nonblocking I/O is enabled using the
				  flag with 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 for‐
				  ward 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  in  getsock‐
				  opt(2)).

	      s			  is not a valid file descriptor.

	      A connection was forcibly closed by a peer.

	      The		  to parameter needs to specify a  destination
				  address for the message.  This is also given
				  if the specified address  contains  unspeci‐
				  fied fields (see inet(7F)).

	      An invalid pointer was specified in the
				  msg or to parameter, or in the structure.

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

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

	      A timeout occurred.

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

	      A length in the	  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 buf‐
				  fer size.

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

	      The destination host is not reachable.

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

				  (LAN) All encapsulations (for example,  Eth‐
				  ernet,  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	inter‐
				  face	hoods  at the modem, the modem failed,
				  the packet switch at	the  remote  end  lost
				  power or failed for some reason, or electri‐
				  cal noise interfered with the	 line  for  an
				  extremely long period of time).

	      No buffer space is available in the system to perform the opera‐
	      tion.

	      No memory is available in the system to perform the operation.

	      The remote system or an intermediate system  in  the  communica‐
	      tions path
				  does	not  support a protocol option sent by
				  the local system.  This option may have been
				  set  using  a	 or  call,  or set as a system
				  parameter.

	      A			  on a socket that is not connected, or a on a
				  socket  that	has  not completed the connect
				  sequence with its peer, or is no longer con‐
				  nected to its peer.

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

	      The		  flag was specified; it is not supported  for
				  AF_UNIX or AF_VME_LINK sockets.

	      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 unless the  process  has	established  a
				  signal handler for this signal, is to termi‐
				  nate the process.

	      Nonblocking I/O is enabled using
				  request and the  requested  operation	 would
				  block.

DEPENDENCIES
       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 guar‐
       antee 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 with

OBSOLESCENCE
       Currently,  the	and  types are the same size.  This is compatible with
       the UNIX 95 and UNIX 03 profiles.  However, in a future release,	 might
       be  a different size.  In that case, the size of the and structures and
       the relative position of their members will be different,  which	 might
       affect  application  behavior.  Applications that use now, where appro‐
       priate, will avoid such migration problems.  On the other hand,	appli‐
       cations	that  need to be portable to the UNIX 95 profile should follow
       the X/Open specification (see xopen_networking(7)).

WARNINGS
       Linking binary objects compiled to  specification  and  binary  objects
       compiled	 to  specification  to the same executable may result in unex‐
       pected behavior, including application abnormal termination  and	 unex‐
       pected socket errors.  See xopen_networking(7) for details and remedy.

FUTURE DIRECTION
       Currently,  the default behavior is the however, it might be changed to
       in a future release.  At that time, any behavior that  is  incompatible
       with might be obsoleted.	 Applications that conform to the X/Open spec‐
       ification now will avoid migration problems (see xopen_networking(7)).

AUTHOR
       and were developed by HP and the University of California, Berkeley.

       The feature is an HP-specific extension to the socket API.

SEE ALSO
       ifconfig(1M), getsockopt(2), recv(2), select(2),	 setsockopt(2),	 shut‐
       down(2),	 socket(2),  thread_safety(5), socket(7), xopen_networking(7),
       inet(7F), IPv6(7P), sctp(7), TCP(7P), UDP(7P), UNIX(7P).

STANDARDS CONFORMANCE
								       send(2)
[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net