include/netio.h File Reference

functions for network I/O More...

#include <sys/types.h>
#include <time.h>

Go to the source code of this file.

Enumerations
enum	conn_shutdown_type { shutdown_clean, shutdown_abort }
Functions
int	net_read (void)
int	net_writen (const char *const *)
int	net_write_multiline (const char *const *)
int	netwrite (const char *)
int	netnwrite (const char *, const size_t)
size_t	net_readbin (size_t, char *)
size_t	net_readline (size_t, char *)
int	data_pending (void)
void	net_conn_shutdown (const enum conn_shutdown_type sd_type)
	shutdown the connection and end the program
Variables
char	linein []
size_t	linelen
time_t	timeout
int	socketd

---

Detailed Description

functions for network I/O

---

Enumeration Type Documentation

enum conn_shutdown_type

Enumerator:

shutdown_clean	do a normal shutdown and notice the partner about the shutdown
shutdown_abort	do hard abort of connection

---

Function Documentation

int data_pending

(

void

)

check if there is data ready to be read without blocking

Return values:

0	if no data
1	if data
-1	on error

void net_conn_shutdown

(

const enum conn_shutdown_type

sd_type

)

shutdown the connection and end the program

Parameters:

sd_type

specifies the way the shutdown should be performed

This is a forward declaration only, every program has to implement this function in a way that matches how it works.

A shutdown_clean shutdown is e.g. sending QUIT to the server and waiting for it's reply. A shutdown with shutdown_abort is e.g. hard dropping of the connection if the client sends spam and has a broken SMTP engine that does not react to error codes.

Calling this function even before the connection was established is fine.

int net_read

(

void

)

read one line from the network

Return values:

0	on success
-1	on error (errno is set)

does not return on timeout, programm will be cancelled

size_t net_readbin	(	size_t	num,
		char *	buf
	)

read a given number of bytes from network as binary data (i.e. without any mangling)

Parameters:

num	number of bytes to read
buf	buffer to store data (must have enough space for (num + 1) bytes)

Returns:

number of bytes read

Return values:

-1

on error

size_t net_readline	(	size_t	num,
		char *	buf
	)

read up to a given number of bytes from network but stop at the first CRLF

Parameters:

num	number of bytes to read, must be < 1002 so everything behind the CRLF can be copied back to lineinn
buf	buffer to store data (must have enough space)

Returns:

number of bytes read

Return values:

-1

on error

The trailing CRLF sequence is kept in the buffer. This function will return an error if it detects a bare CR or LF in the middle of the input data, but it cannot detect if the CR goes in one call and LF in the next, so it will allow the output to be just LF or to end in CR.

int net_write_multiline

(

const char *const *

s

)

write multiple lines to the network

Parameters:

s	array of strings to send

Return values:

0	on success
-1	on error (errno is set)

This combines all given strings into one buffer and send them out to the network. This allows the underlying network stack to use the least sensible number of packets, reducing network latency. If memory allocation fails for the intermediate buffer the lines may be send in smaller chunks, which is less efficient but is no other loss in functionality.

Does not return on timeout, programm will be cancelled.

If one part or multiple consecutive parts covers a whole SMTP line this line must conform to the SMTP line length limit (512 bytes).

int net_writen

(

const char *const *

s

)

write one line to the network, fold if needed

Parameters:

s	array of strings to send

Return values:

0	on success
-1	on error (errno is set)

does not return on timeout, programm will be cancelled

Warning:

s[0] must be short enough to fit completely into the buffer

every s[] must not have a sequence longer then 506 characters without a space (' ') in them

int netnwrite	(	const char *	s,
		const size_t	l
	)

write one line to the network

Parameters:

s	line to be written (nothing else it written so it should contain CRLF)
l	length of s

Return values:

0	on success
-1	on error (errno is set)

does not return on timeout, programm will be cancelled

int netwrite

(

const char *

s

)

write one line to the network

Parameters:

s	line to be written (nothing else it written so it should contain CRLF)

Return values:

0	on success
-1	on error (errno is set)

-does not return on timeout, programm will be cancelled -same as net_write but expects that line is <= 512 characters and includes CRLF

---

Variable Documentation

char linein[]

buffer for the line to read: max 1000 chars including CRLF, leading extra '.', closing '\0'

size_t linelen

length of the line

int socketd

the descriptor where messages to network are written to

time_t timeout

how long to wait for data