The <socket.h>
header defines several functions useful to sockets.
Structures and Types
sockaddr Struct
Purpose
Defines a structure used by the kernel to store most addresses.
Declared In
posix/sys/time.h
Prototype
struct sockaddr { sa_family_t sa_family; char sa_data[14]; }
Fields
socklen_t Typedef
Purpose
Definitions related to sockets: types, address families, options.
Declared In
posix/sys/socket.h
Prototype
typedef unsigned int socklen_t
Functions and Macros
accept Function
Purpose
Accepts a connection on a socket by extracting the first connection request on the queue of pending connections, creating a new socket with the same properties of sock
and allocating a new file descriptor for the socket.
Declared In
posix/sys/socket.h
Prototype
int accept ( intsock
, struct sockaddr *addr
, socklen_t *addrlen
)
Parameters
-
→ sock
- A socket that has been created with
socket()
, bound to an address withbind()
, and listening for connections after alisten()
. -
← addr
- A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
-
↔ addrlen
- Initially contains the amount of space pointed to by
addr
; on return, it contains the actual length (in bytes) of the address returned.
Returns
Returns a non-negative integer that is a descriptor for the accepted socket. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
bind()
, connect()
, listen()
, select()
, socket()
bind Function
Purpose
Assigns a name to an unnamed socket.
Declared In
posix/sys/socket.h
Prototype
int bind ( intsock
, const struct sockaddr *addr
, socklen_taddrlen
)
Parameters
-
→ sock
- A socket that has been created with
socket()
that exists in a namespace but has no name defined. -
← addr
- A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
-
↔ addrlen
- Initially contains the amount of space pointed to by
addr
; on return, it contains the actual length (in bytes) of the address returned.
Returns
Returns zero (0) if the bind is successful. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
connect()
, getsockname()
, listen()
, socket()
connect Function
Purpose
Initiates a connection on a socket.
Declared In
posix/sys/socket.h
Prototype
int connect ( intsock
, const struct sockaddr *addr
, socklen_taddrlen
)
Parameters
-
→ sock
- A socket.
-
← addr
- A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
-
↔ addrlen
- Initially contains the amount of space pointed to by
addr
; on return, it contains the actual length (in bytes) of the address returned.
Returns
Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
accept()
, getsockname()
, getsockopt()
, select()
, socket()
getpeername Function
Purpose
Gets the name of the connected peer.
Declared In
posix/sys/socket.h
Prototype
int getpeername ( intsock
, struct sockaddr *addr
, socklen_taddrlen
)
Parameters
-
→ sock
- A socket.
-
← addr
- A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
-
↔ addrlen
- Initially contains the amount of space pointed to by
addr
; on return, it contains the actual length (in bytes) of the address returned.
Returns
Returns the name of the peer connected to the specified socket.
Compatibility
This function is not in the C99 specification.
See Also
accept()
, bind()
, getsockname()
, socket()
getsockname Function
Purpose
Declared In
posix/sys/socket.h
Prototype
int getsockname ( intsock
, struct sockaddr *addr
, socklen_taddrlen
)
Parameters
-
→ sock
- A socket.
-
← addr
- A result parameter that is filled in with the source address of the connecting entity, as known to the communications layer.
-
↔ addrlen
- Initially contains the amount of space pointed to by
addr
; on return, it contains the actual length (in bytes) of the address returned.
Returns
Returns the current name for the specified socket.
Compatibility
This function is not in the C99 specification.
See Also
getsockopt Function
Purpose
Declared In
posix/sys/socket.h
Prototype
int getsockopt ( intsock
, intlevel
, intoption
, void *optval
, socklen_t *optlen
)
Parameters
-
→ sock
- A socket.
-
→ level
- To manipulate options at the socket level,
level
is specified asSOL_SOCKET
. -
→ option
-
option
and any specified options are passed uninterpreted to the appropriate protocol module for interpretation.
Returns
Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
getprotoent()
, ioctl()
, select()
, socket()
, setsockopt()
listen Function
Purpose
Listens for connections on a socket.
Declared In
posix/sys/socket.h
Prototype
int listen ( intsock
, intbacklog
)
Parameters
Returns
Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
recv Function
Purpose
Normally used only on a connected socket and is identical to recvfrom()
with a NULL
addr
parameter.
Declared In
posix/sys/socket.h
Prototype
ssize_t recv ( intsock
, void *data
, size_tdatalen
, intflags
)
Parameters
-
→ sock
- A socket.
-
→ data
- The message.
-
→ datalen
- The length of the message.
-
→ flags
- ORs together one or more of the values:
MSG_OOB
,MSG_PEEK
,MSG_WAITALL
.
Returns
Returns the length of the message upon successful completion. Otherwise, -1 is returned and the global variable errno
is set to indicate the error. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from.
Compatibility
This function is not in the C99 specification.
See Also
connect()
, recvfrom()
, recvmsg()
recvfrom Function
Purpose
Receives messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented.
Declared In
posix/sys/socket.h
Prototype
ssize_t recvfrom ( intsock
, void *data
, size_tdatalen
, intflags
, struct sockaddr *addr
, socklen_t *addrlen
)
Parameters
-
→ sock
- A socket.
-
→ data
- The message.
-
→ datalen
- The length of the message.
-
→ flags
- ORs together one or more of the values:
MSG_OOB
,MSG_PEEK
,MSG_WAITALL
. -
→ addr
- If
addr
is non-NULL
, and the socket is not connection-oriented, the source address of the message is filled in. -
← addrlen
- Initially contains the amount of space pointed to by
addr
; on return, it contains the actual length (in bytes) of the address stored there.
Returns
Returns the length of the message upon successful completion. Otherwise, -1 is returned and the global variable errno
is set to indicate the error. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from.
Compatibility
This function is not in the C99 specification.
See Also
recvmsg Function
Purpose
Receives messages from a socket, and may be used to receive data on a socket whether or not it is connection-oriented.
Declared In
posix/sys/socket.h
Prototype
ssize_t recvmsg ( intsd
, struct msghdr *msg
, intflags
)
Parameters
-
→ sd
- A socket.
-
→ msg
- The message.
-
→ flags
- ORs together one or more of the values:
MSG_OOB
,MSG_PEEK
,MSG_WAITALL
.
Returns
Returns the length of the message upon successful completion. Otherwise, -1 is returned and the global variable errno
is set to indicate the error. If a message is too long to fit in the supplied buffer, excess bytes may be discarded depending on the type of socket the message is received from.
Compatibility
This function is not in the C99 specification.
See Also
send Function
Purpose
Sends a message from a socket.
Declared In
posix/sys/socket.h
Prototype
ssize_t send ( intsock
, const void *data
, size_tdatalen
, intflags
)
Parameters
-
→ sock
- A socket.
-
→ data
- The message.
-
→ datalen
- The length of the message.
-
→ flags
- ORs together one or more of the values:
MSG_OOB
,MSG_DONTROUTE
.
Returns
Returns the number of characters sent. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Comments
May be used only when the socket is in a connected state.
Compatibility
This function is not in the C99 specification.
See Also
sendmsg Function
Purpose
Sends a message from a socket.
Declared In
posix/sys/socket.h
Prototype
ssize_t sendmsg ( intsd
, const struct msghdr *msg
, intflags
)
Parameters
-
→ sd
- A socket.
-
→ msg
- The message.
-
→ flags
- ORs together one or more of the values:
MSG_OOB
,MSG_DONTROUTE
.
Returns
Returns the number of characters sent. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
sendto Function
Purpose
Sends a message from a socket.
Declared In
posix/sys/socket.h
Prototype
ssize_t sendto ( intsock
, const void *data
, size_tdatalen
, intflags
, const struct sockaddr *addr
, socklen_taddrlen
)
Parameters
-
→ sock
- A socket.
-
→ data
- The message.
-
→ datalen
- The length of the message.
-
→ flags
- ORs together one or more of the values:
MSG_OOB
,MSG_DONTROUTE
. -
→ addr
- If
addr
is non-NULL
, and the socket is not connection-oriented, the source address of the message is filled in. -
← addrlen
- Initially contains the amount of space pointed to by
addr
; on return, it contains the actual length (in bytes) of the address stored there.
Returns
Returns the number of characters sent. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
setsockopt Function
Purpose
Declared In
posix/sys/socket.h
Prototype
int setsockopt ( intsock
, intlevel
, intoption
, const void *optval
, socklen_toptlen
)
Parameters
-
→ sock
- A socket.
-
→ level
- To manipulate options at the socket level,
level
is specified asSOL_SOCKET
. -
→ option
- Any specified option(s) passed uninterpreted to the appropriate protocol module for interpretation.
-
→ optval
- Used to access option values. Identifies a buffer in which the value for the requested option is returned.
-
→ optlen
- Used to access option values. Identifies a buffer in which the length for the requested option is returned.
Returns
Returns zero (0) if the connection or binding is successful. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
See Also
getprotoent()
, getsockopt()
, ioctl()
, select()
, socket()
shutdown Function
Purpose
Disables subsequent send and/or receive operations on a socket.
Declared In
posix/sys/socket.h
Prototype
int shutdown ( intsock
, intdirection
)
Parameters
-
→ sock
- A socket.
-
→ direction
- Specifies the type of shutdown. The values are as follows:
-
SHUT_RD
- Disables further receive operations.
-
SHUT_WR
- Disables further send operations.
-
SHUT_RDWR
- Disables further send and receive operations.
Returns
Returns zero (0) upon successful completion. Otherwise, 1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.
socket Function
Purpose
Creates an endpoint for communication.
Declared In
posix/sys/socket.h
Prototype
int socket ( intfamily
, inttype
, intproto
)
Parameters
-
→ family
- A communications domain within which communication takes place; this selects the protocol family that should be used.
-
→ type
- The semantics of communication.
-
→ proto
- A particular protocol to be used with the socket.
Returns
Returns a descriptor referencing the socket. Otherwise, -1 is returned and the global variable errno
is set to indicate the error.
Compatibility
This function is not in the C99 specification.