NAME
bind — bind an address to a socket
SYNOPSIS
#include <sys/socket.h>
AF_CCITT only
#include <x25/x25addrstr.h>
AF_INET and AF_VME_LINK only
#include <netinet/in.h>
AF_UNIX only
#include <sys/un.h>
int bind(int s, const void *addr, int addrlen);
_XOPEN_SOURCE_EXTENDED only (UNIX 98)
int bind(int s, const struct sockaddr *addr, socklen_t addrlen);
Obsolescent _XOPEN_SOURCE_EXTENDED only (UNIX 95)
int bind(int s, const struct sockaddr *addr, size_t addrlen);
DESCRIPTION
The
bind()
system call assigns an address to an unbound socket.
When a socket is created with
socket(),
it exists in an address space (address family)
but has no address assigned.
bind()
causes the socket whose descriptor is
s
to become bound to the address specified in the
socket address structure pointed to by
addr.
addrlen
must specify the size of the address structure.
Since the size of the socket address structure
varies between socket address families,
the correct socket address structure
should be used with each address family
(for example,
struct sockaddr_in
for AF_INET and AF_VME_LINK, and
struct sockaddr_un
for AF_UNIX).
Typically, the
sizeof()
function is used to pass this value in the
bind()
call (for example,
sizeof(struct sockaddr_in)).
The rules used in address binding vary between communication domains.
For example, when binding an AF_UNIX socket to a path name (such as
/tmp/mysocket),
an open file having that name is created in the file system.
When the bound socket is closed,
that file still exists unless it is removed or unlinked.
When binding an AF_INET socket,
sin_port
can be a port number or it can be zero.
If
sin_port
is zero, the system assigns an unused port number
automatically.
AF_VME_LINK Only
The
bind()
system call is used only by servers and not clients.
RETURN VALUE
bind()
returns the following values:
- 0
Successful completion.
- -1
Failure.
errno
is set to indicate the error.
ERRORS
If
bind()
fails,
errno
is set to one of the following values.
- [EACCES]
The requested address is protected, and the current user
has inadequate permission to access it.
(This error can be returned by AF_INET only.)
- [EADDRINUSE]
The specified address is already in use.
- [EADDRNOTAVAIL]
The specified address is invalid or not available from the local
machine,
or for AF_CCITT sockets which use "wild card" addressing,
the specified address space overlays the address space
of an existing bind.
- [EAFNOSUPPORT]
The specified address is not a valid address
for the address family of this socket.
- [EBADF]
s
is not a valid file descriptor.
- [EDESTADDRREQ]
No
addr
parameter was specified.
- [EFAULT]
addr
is not a valid pointer.
- [EINVAL]
The socket is already bound to an address,
the socket has been shut down,
addrlen
is a bad value, or an attempt was made to
bind()
an AF_UNIX socket to an NFS-mounted (remote) name.
AF_CCITT:
The protocol-ID length is negative or greater than 8,
the X.121 address string contains an illegal character,
or the X.121 address string is greater than 15 digits long.
AF_VME_LINK:
An explicit bind can be made only to a well-known port.
- [ENETDOWN]
The
x25ifname
field name specifies an interface that was shut down,
or never initialized, or whose Level 2 protocol
indicates that the link is not working:
Wires might be broken,
the interface hoods on the modem are broken,
the modem failed, the phone connection failed
(this error can be returned by AF_CCITT only),
noise interfered with the line for a long period of time.
- [ENETUNREACH]
The X.25 Level 2 protocol is down.
The X.25 link is not working:
Wires might be broken, or connections are loose on the interface
hoods at the modem, the modem failed, or noise interfered with
the line for an extremely long period of time.
- [ENOBUFS]
No buffer space is available.
The
bind()
cannot complete.
- [ENOMEM]
No memory is available.
The
bind()
cannot complete.
- [ENODEV]
The
x25ifname
field name specifies a nonexistent interface.
(This error can be returned by AF_CCITT only.)
- [ENOTSOCK]
s
is a valid file descriptor, but it is not a socket.
- [EOPNOTSUPP]
The socket referenced by
s
does not support address binding.
- [EISCONN]
The connection is already bound.
(AF_VME_LINK.)
OBSOLESCENCE
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, but that should not
adversely affect application behavior in this case.
Applications may use
socklen_t
now. But applications that need to be portable to
the UNIX 95 profile should follow the X/Open specification (see
xopen_networking(7)).
FUTURE DIRECTION
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)).
MULTITHREAD USAGE
The
bind()
system call is thread-safe.
It has a cancellation point; and
it is async-cancel safe, async-signal safe, and fork-safe.
AUTHOR
bind()
was developed by HP and the University of California, Berkeley.
SEE ALSO
connect(2),
getsockname(2),
listen(2),
socket(2),
af_ccitt(7F),
af_vme_link(7F),
inet(7F),
socketx25(7),
tcp(7P),
udp(7P),
unix(7P),
xopen_networking(7).
STANDARDS CONFORMANCE
bind(): XPG4
