skt.h


Headers Index Help      Within this page: Functions Constants Variables


Overview

A library package for handling sockets

- Written by M.C.Gregorie, 2003.

The functions in this package are wrappers round the UNIX sockets library. Their purpose is to minimise the repetitive coding involved in using the raw sockets interface. There are three groups of functions in this package:

Functions for use in servers that accept incoming connections:

Functions for use in clients that make outgoing connections:

General purpose functions that can be used in clients or servers:

Programs can use all three groups if they must accept connections as well as making connections to other programs.

This package operates transparently over named pipes or TCP/IP sockets. The only place where this needs to be specified is in the parameters of skt_xxx() functions that open connections to other programs.

This collection of functions is compiled to form part of the libenviron.a library, which must be linked if any of of its constituent functions are called.

Compilation

The calling programs should include skt.h and must be linked using -lenviron.

environ - C programming support functions
Copyright (C) 2005 Martin C Gregorie

This program is free software; you can redistribute it and/or modify it under the terms of the Lesser GNU General Public License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the Lesser GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Contact Martin Gregorie at martin@gregorie.org

Functions


skt_accept

#include <skt.h>

int  skt_accept(int listener);

Create a server connection for an incoming request detected by the listener. listener is the fd of the listener socket. Returns the fd of the connection that has been accepted on success or a negative number if an error was detected.

In: skt.c

Return to the top

skt_close

#include <skt.h>

void skt_close(int skt);

Used by client or server to close an open (non-listener) connection.

In: skt.c

Return to the top

skt_closelistener

#include <skt.h>

void skt_closelistener(int skt, char *pipe);

Used by a server to close an open listener connection for possible re-use. skt is the fd of the listener. *pipe is only needed if the listener was listening on a named pipe: it which case it is the name of the pipe.

In: skt.c

Return to the top

skt_connect

#include <skt.h>

int skt_connect(char *name, int portnum);

Used by a client to open a connection to a server. Multiple simultaneous connections are permitted. If portnum is non zero it will attempt to connect to the host given by name using the port in portnum. If portnum is zero it will attempt to connect to a named pipe using the name in name.

It returns the fd of the connection on success or a negative number if the connection attempt failed.

In: skt.c

Return to the top

skt_debug

#include <skt.h>

void skt_debug(int d);

Set debugging conditions. When the debug level is zero no tracing occurs. A debug level of 1 traces calls to the functions in this package. It is useful for debugging the calling program. A debug level of 2 or greater is used to trace the internals of the more complex functions on this package.

In: skt.c

Return to the top

skt_error

#include <skt.h>

char *skt_error(void);

Return a string describing the last error detected.

In: skt.c

Return to the top

skt_getname

#include <skt.h>

int skt_getname(int skt, int locality, char *host, int lth);

Retrieves the host name at one end of the connection. skt is the fd of the socket, locality specifies which end of the connection is to be interrogated. Either LOCAL_HOST or REMOTE_HOST must be specified. host is the buffer that will receive the hostname and lth is the buffer length. It returns 0 on success and -1 on failure.

In: skt.c

Return to the top

skt_getport

#include <skt.h>

int skt_getport(int skt, int locality);

Retrieves the port number used by the socket whose fd is in skt. locality specifies which end of the connection is to be interrogated. Either LOCAL_HOST or REMOTE_HOST must be specified.

It returns the port number on success and -1 on failure.

In: skt.c

Return to the top

skt_listen

#include <skt.h>

int skt_listen(char *name, int portnum);

Create a listener for a server. The listener can operate on a TCP/IP socket or a named pipe. If portnum is zero a named pipe is created from name. If non-zero, portnum is the port to be used. It returns the fd of the listener on success and a negative number if an error was detected.

NOTE: there can be only one active listener per process but it can be closed and reopened.

In: skt.c

Return to the top

skt_receive

#include <skt.h>

int skt_receive(int skt, char *response, int length);

Used by client or server to receive a message on an open connection. It is a wrapper for recv(). skt is the fd of the socket, *response is the receiving buffer and length is the buffer length. It returns the same result codes as recv(). Negative result codes are errors and zero means the remote process has closed its connection.

In: skt.c

Return to the top

skt_send

#include <skt.h>

int skt_send(int skt, char* request, int length);

Used by client or server to send a message on an open connection. It is a wrapper for send(). skt is the fd of the socket. request is a byte array containing the message to be sent. length is the number of bytes to be sent. It returns the same result codes as send().

In: skt.c

Return to the top

Constants

LOCAL_HOST
#define LOCAL_HOST   0
REMOTE_HOST
#define REMOTE_HOST  1

Return to the top

Public variables were not declared.
Return to the top