Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

18    socket.h

Palm OS® Protein C/C++ Compiler Language & Library Reference

Palm OS® Developer Suite

     

The <socket.h> header defines several functions useful to sockets.

Structures and Types ^TOP^

sockaddr Struct ^TOP^

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

sa_family
The address family.
sa_data
The address value.

socklen_t Typedef ^TOP^

Purpose

Definitions related to sockets: types, address families, options.

Declared In

posix/sys/socket.h

Prototype

typedef unsigned int socklen_t

Functions and Macros ^TOP^

accept Function ^TOP^

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 (
   int sock,
   struct sockaddr *addr,
   socklen_t *addrlen
)

Parameters

sock
A socket that has been created with socket(), bound to an address with bind(), and listening for connections after a listen().
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 ^TOP^

Purpose

Assigns a name to an unnamed socket.

Declared In

posix/sys/socket.h

Prototype

int bind (
   int sock,
   const struct sockaddr *addr,
   socklen_t addrlen
)

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 ^TOP^

Purpose

Initiates a connection on a socket.

Declared In

posix/sys/socket.h

Prototype

int connect (
   int sock,
   const struct sockaddr *addr,
   socklen_t addrlen
)

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 ^TOP^

Purpose

Gets the name of the connected peer.

Declared In

posix/sys/socket.h

Prototype

int getpeername (
   int sock,
   struct sockaddr *addr,
   socklen_t addrlen
)

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 ^TOP^

Purpose

Gets the socket name.

Declared In

posix/sys/socket.h

Prototype

int getsockname (
   int sock,
   struct sockaddr *addr,
   socklen_t addrlen
)

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

bind(), socket()

getsockopt Function ^TOP^

Purpose

Gets the options on sockets.

Declared In

posix/sys/socket.h

Prototype

int getsockopt (
   int sock,
   int level,
   int option,
   void *optval,
   socklen_t *optlen
)

Parameters

sock
A socket.
level
To manipulate options at the socket level, level is specified as SOL_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 ^TOP^

Purpose

Listens for connections on a socket.

Declared In

posix/sys/socket.h

Prototype

int listen (
   int sock,
   int backlog
)

Parameters

sock
A socket.
backlog
The maximum length the queue of pending connections may grow to.

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(), connect(), socket()

recv Function ^TOP^

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 (
   int sock,
   void *data,
   size_t datalen,
   int flags
)

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 ^TOP^

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 (
   int sock,
   void *data,
   size_t datalen,
   int flags,
   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

connect(), recv(), recvmsg()

recvmsg Function ^TOP^

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 (
   int sd,
   struct msghdr *msg,
   int flags
)

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

connect(), recv(), recvfrom()

send Function ^TOP^

Purpose

Sends a message from a socket.

Declared In

posix/sys/socket.h

Prototype

ssize_t send (
   int sock,
   const void *data,
   size_t datalen,
   int flags
)

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

select(), sendmsg(), sendto()

sendmsg Function ^TOP^

Purpose

Sends a message from a socket.

Declared In

posix/sys/socket.h

Prototype

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

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

select(), send(), sendto()

sendto Function ^TOP^

Purpose

Sends a message from a socket.

Declared In

posix/sys/socket.h

Prototype

ssize_t sendto (
   int sock,
   const void *data,
   size_t datalen,
   int flags,
   const 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_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

select(), send(), sendmsg()

setsockopt Function ^TOP^

Purpose

Sets options on sockets.

Declared In

posix/sys/socket.h

Prototype

int setsockopt (
   int sock,
   int level,
   int option,
   const void *optval,
   socklen_t optlen
)

Parameters

sock
A socket.
level
To manipulate options at the socket level, level is specified as SOL_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 ^TOP^

Purpose

Disables subsequent send and/or receive operations on a socket.

Declared In

posix/sys/socket.h

Prototype

int shutdown (
   int sock,
   int direction
)

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 ^TOP^

Purpose

Creates an endpoint for communication.

Declared In

posix/sys/socket.h

Prototype

int socket (
   int family,
   int type,
   int proto
)

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.

See Also

getsockopt()