WSACleanup()

Description

Terminate use of the Windows Sockets DLL. 

#include <winsock.h>

int PASCAL FAR WSACleanup ( void );

Remarks

An application is required to perform a (successful) WSAStartup() call before it can use Windows Sockets services. When it has completed the use of Windows Sockets, the application must call WSACleanup() to deregister itself from a Windows Sockets implementation and allow the implementation to free any resources allocated on behalf of the application or DLL. Any open SOCK_STREAM sockets that are connected when WSACleanup() is called are reset; sockets which have been closed with closesocket() but which still have pending data to be sent are not affected--the pending data is still sent.

There must be a call to WSACleanup() for every call to WSAStartup() made by a task. Only the final WSACleanup() does the actual cleanup; the preceding calls simply decrement an internal reference count in the Windows Sockets DLL. A naive application may ensure that WSACleanup() was called enough times by calling WSACleanup() in a loop until it returns WSANOTINITIALISED.

Return Value

The return value is 0 if the operation was successful. Otherwise the value SOCKET_ERROR is returned, and a specific error number may be retrieved by calling WSAGetLastError().

Comments

Attempting to call WSACleanup() from within a blocking hook and then failing to check the return code is a common Windows Sockets programming error. If an application needs to quit while a blocking call is outstanding, the application must first cancel the blocking call with WSACancelBlockingCall() then issue the WSACleanup() call once control has been returned to the application.

Notes For Windows Sockets Suppliers

Well-behaved Windows Sockets applications will make a WSACleanup() call to indicate deregistration from a Windows Sockets implementation. This function can thus, for example, be utilized to free up resources allocated to the specific application.

A Windows Sockets implementation must be prepared to deal with an application which terminates without invoking WSACleanup() -- for example, as a result of an error.

In a multithreaded environment, WSACleanup() terminates Windows Sockets operations for all threads.

A Windows Sockets implementation must ensure that WSACleanup() leaves things in a state in which the application can invoke WSAStartup() to re-establish Windows Sockets usage.

Error Codes