4.2 Database Routines

4.2.1 gethostbyaddr()

Description

Get host information corresponding to an address.

#include <winsock.h>

struct hostent FAR * PASCAL FAR gethostbyaddr ( const char FAR * addr, int len, int type );


addr

A pointer to an address in network byte order.

len

The length of the address, which must be 4 for PF_INET addresses.

type

The type of the address, which must be PF_INET.


Remarks

gethostbyaddr() returns a pointer to the following structure which contains the name(s) and address which correspond to the given address.


struct hostent {

char FAR * h_name;

char FAR * FAR * h_aliases;

short h_addrtype;

short h_length;

char FAR * FAR * h_addr_list;

};

The members of this structure are:

Element Usage

h_name Official name of the host (PC).

h_aliases A NULL-terminated array of alternate names.

h_addrtype

The type of address being returned; for Windows Sockets this is always PF_INET.

h_length

The length, in bytes, of each address; for PF_INET, this is always 4.

h_addr_list

A NULL-terminated list of addresses for the host. Addresses are returned in network byte order.


The macro h_addr is defined to be h_addr_list[0] for compatibility with older software.

The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.


Return Value

If no error occurs, gethostbyaddr() returns a pointer to the hostent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().


Error Codes

WSANOTINITIALISED

WSAENETDOWN


WSAHOST_NOT_FOUND
WSATRY_AGAIN

WSANO_RECOVERY

WSANO_DATA

WSAEINPROGRESS

WSAEINTR

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Authoritative Answer Host not found.
Non-Authoritative Host not found, or SERVERFAIL.
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
Valid name, no data record of requested type.
A blocking Windows Sockets operation is in progress.
The (blocking) call was canceled via WSACancelBlockingCall().


See Also

WSAAsyncGetHostByAddr(), gethostbyname(),


4.2.2 gethostbyname()

Description

Get host information corresponding to a hostname.

#include <winsock.h>

struct hostent FAR * PASCAL FAR gethostbyname ( const char FAR * name );


name

A pointer to the name of the host.


Remarks

gethostbyname() returns a pointer to a hostent structure as described under gethostbyaddr(). The contents of this structure correspond to the hostname name.


The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

A gethostbyname() implementation must not resolve IP address strings passed to it. Such a request should be treated exactly as if an unknown host name were passed. An application with an IP address string to resolve should use inet_addr() to convert the string to an IP address, then gethostbyaddr() to obtain the hostent structure.

Return Value

If no error occurs, gethostbyname() returns a pointer to the hostent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().


Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSAHOST_NOT_FOUND
WSATRY_AGAIN

WSANO_RECOVERY

WSANO_DATA
WSAEINPROGRESS

WSAEINTR

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Authoritative Answer Host not found.
Non-Authoritative Host not found, or SERVERFAIL.
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
Valid name, no data record of requested type.
A blocking Windows Sockets operation is in progress.
The (blocking) call was canceled via WSACancelBlockingCall().


See Also

WSAAsyncGetHostByName(), gethostbyaddr()


4.2.3 gethostname()

Description

Return the standard host name for the local machine.

#include <winsock.h>

int PASCAL FAR gethostname ( char FAR * name, int namelen );


name

A pointer to a buffer that will receive the host name.

namelen

The length of the buffer.


Remarks

This routine returns the name of the local host into the buffer specified by the name parameter. The host name is returned as a null-terminated string. The form of the host name is dependent on the Windows Sockets implementation--it may be a simple host name, or it may be a fully qualified domain name. However, it is guaranteed that the name returned will be successfully parsed by gethostbyname() and WSAAsyncGetHostByName().

Return Value

If no error occurs, gethostname() returns 0, otherwise it returns SOCKET_ERROR and a specific error code may be retrieved by calling WSAGetLastError().


Error Codes

WSAEFAULT
WSANOTINITIALISED

WSAENETDOWN

WSAEINPROGRESS

The namelen parameter is too small
A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
A blocking Windows Sockets operation is in progress.


See Also

gethostbyname(), WSAAsyncGetHostByName().


4.2.4 getprotobyname()

Description

Get protocol information corresponding to a protocol name.

#include <winsock.h>

struct protoent FAR * PASCAL FAR getprotobyname ( const char FAR * name );


name

A pointer to a protocol name.


Remarks

getprotobyname() returns a pointer to the following structure which contains the name(s) and protocol number which correspond to the given protocol name.


struct protoent {

char FAR * p_name;

char FAR * FAR * p_aliases;

short p_proto;

};

The members of this structure are:

Element Usage

p_name Official name of the protocol.

p_aliases A NULL-terminated array of alternate names.

p_proto The protocol number, in host byte order.

The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never attempt to modify this structure or to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value

If no error occurs, getprotobyname() returns a pointer to the protoent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().


Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSANO_RECOVERY

WSANO_DATA
WSAEINPROGRESS

WSAEINTR

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
Valid name, no data record of requested type.
A blocking Windows Sockets operation is in progress.
The (blocking) call was canceled via WSACancelBlockingCall().


See Also

WSAAsyncGetProtoByName(), getprotobynumber()


4.2.5 getprotobynumber()

Description

Get protocol information corresponding to a protocol number.

#include <winsock.h>

struct protoent FAR * PASCAL FAR getprotobynumber ( int number );


number

A protocol number, in host byte order.


Remarks

This function returns a pointer to a protoent structure as described above in getprotobyname(). The contents of the structure correspond to the given protocol number.
The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value

If no error occurs, getprotobynumber() returns a pointer to the protoent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().


Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSANO_RECOVERY

WSANO_DATA
WSAEINPROGRESS

WSAEINTR

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
Valid name, no data record of requested type.
A blocking Windows Sockets operation is in progress.
The (blocking) call was canceled via WSACancelBlockingCall().


See Also

WSAAsyncGetProtoByNumber(), getprotobyname()


4.2.6 getservbyname()

Description

Get service information corresponding to a service name and protocol.

#include <winsock.h>

struct servent FAR * PASCAL FAR getservbyname ( const char FAR * name, const char FAR * proto );


name

A pointer to a service name.

proto

An optional pointer to a protocol name. If this is NULL, getservbyname() returns the first service entry for which the name matches the s_name or one of the s_aliases. Otherwise getservbyname() matches both the name and the proto.


Remarks

getservbyname() returns a pointer to the following structure which contains the name(s) and service number which correspond to the given service name.


struct servent {

char FAR * s_name;

char FAR * FAR * s_aliases;

short s_port;

char FAR * s_proto;

};

The members of this structure are:

Element Usage

s_name Official name of the service.

s_aliases A NULL-terminated array of alternate names.

s_port The port number at which the service may be contacted. Port numbers are returned in network byte order.

s_proto The name of the protocol to use when contacting the service.

The pointer which is returned points to a structure which is allocated by the Windows Sockets library. The application must never attempt to modify this structure or to free any of its components. Furthermore only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value

If no error occurs, getservbyname() returns a pointer to the servent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().


Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSANO_RECOVERY

WSANO_DATA
WSAEINPROGRESS

WSAEINTR

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
Valid name, no data record of requested type.
A blocking Windows Sockets operation is in progress.
The (blocking) call was canceled via WSACancelBlockingCall().


See Also

WSAAsyncGetServByName(), getservbyport()


4.2.7 getservbyport()

Description

Get service information corresponding to a port and protocol.

#include <winsock.h>

struct servent FAR * PASCAL FAR getservbyport ( int port, const char FAR * proto );


port

The port for a service, in network byte order.

proto

An optional pointer to a protocol name. If this is NULL, getservbyport() returns the first service entry for which the port matches the s_port. Otherwise getservbyport() matches both the port and the proto.


Remarks

getservbyport() returns a pointer a servent structure as described above for getservbyname().


The pointer which is returned points to a structure which is allocated by the Windows Sockets implementation. The application must never attempt to modify this structure or to free any of its components. Furthermore, only one copy of this structure is allocated per thread, and so the application should copy any information which it needs before issuing any other Windows Sockets API calls.

Return Value

If no error occurs, getservbyport() returns a pointer to the servent structure described above. Otherwise it returns a NULL pointer and a specific error number may be retrieved by calling WSAGetLastError().


Error Codes

WSANOTINITIALISED

WSAENETDOWN

WSANO_RECOVERY

WSANO_DATA
WSAEINPROGRESS

WSAEINTR

A successful WSAStartup() must occur before using this API.
The Windows Sockets implementation has detected that the network subsystem has failed.
Non recoverable errors, FORMERR, REFUSED, NOTIMP.
Valid name, no data record of requested type.
A blocking Windows Sockets operation is in progress.
The (blocking) call was canceled via WSACancelBlockingCall().


See Also

WSAAsyncGetServByPort(), getservbyname()