.TH screen 2.SH Namescreen \- gateway packet screening facility.SH Syntax.nf#include <sys/types.h>#include <net/gw_screen.h>int mode;struct screen_data sdata;struct screen_stats sstats;.PPioctl(s, SIOCSCREENON, (caddr_t)&\fImode\fP);ioctl(s, SIOCSCREEN, (caddr_t)&\fIsdata\fP);ioctl(s, SIOCSCREENSTATS, (caddr_t)&\fIsstats\fP);.fi.SH ArgumentsThe interface to thegateway screen facility is a set of ioctlrequests.  All these requests are meant to be used on a file descriptorcreated by the.MS socket 2system call..IP "SIOCSCREENON" 10The.I modeparameter, passed by reference,can be .PN SCREENMODE_OFF ,.PN SCREENMODE_ON ,or.PN SCREENMODE_NOCHANGE .Upon completion of the system call, the.I modeparameter contains the previous value of the screen mode.Unprivileged users may only use the.PN SCREENMODE_NOCHANGErequest..IP "SIOCSCREEN" This is the most important request and is described below.Only the super-user may make this request..IP "SIOCSCREENSTATS" Returns, by reference using the.I sstatsparameter, statistics in this structure:.EX 0struct screen_stats {	u_long	ss_packets;	/* total packets screened */	u_long	ss_nobuffer;	/* dropped, buffer was full */	u_long	ss_accept;	/* total accepted */	u_long	ss_reject;	/* total rejected */	u_long	ss_badsync;	/* dropped, user was out of sync */	u_long	ss_stale;	/* dropped, too old */};.EE.SH Description.NXR "gateway screening".NXR "gateway screen facility".NXR "network packets" "and the gateway screen facility".NXR "screen system call"The gateway screenfacility allows a user-level process to decide which network packets should beforwarded by the kernel (when the system is acting as a gateway).When the screen mode is set to ``off,'' all packets are forwarded normally;when the screen mode is set to ``on,'' all packets that would be forwardedmust be approved through the use of this facility..SS Use of SIOCSCREENThe.PN SIOCSCREENrequest is used in the main loop ofthe user-level daemon.  Each time it is called, it returns(by reference using the.I sdataparameter)a.PN screen_datastructurecontaining a prefix of a packet (normally containing thepacket headers) and some additional information:.EX 0struct screen_data_hdr {	short	sdh_count;	/* length of entire record */	short	sdh_dlen;	/* bytes of packet header */	u_long	sdh_xid;	/* transaction ID */	struct timeval	sdh_arrival;	/* time packet arrived */	short	sdh_family;	/* address family */	int	sdh_action;	/* disposition for packet */#define	SCREEN_ACCEPT	0x0001	/* Accept this packet */#define	SCREEN_DROP	0x0000	/* Do not accept this packet */#define	SCREEN_NOTIFY	0x0002	/* Notify sender of failure */#define	SCREEN_NONOTIFY	0x0000	/* Do not notify sender */};struct screen_data {	struct screen_data_hdr sd_hdr;	char sd_data[SCREEN_DATALEN];	/* sd_dlen bytes of packet header */};#define	sd_count	sd_hdr.sdh_count#define	sd_dlen		sd_hdr.sdh_dlen#define	sd_xid		sd_hdr.sdh_xid#define	sd_action	sd_hdr.sdh_action#define	sd_arrival	sd_hdr.sdh_arrival#define	sd_family	sd_hdr.sdh_family.EEThe.I sd_familyfield indicates the protocol family (for example,.PN AF_INET )under which the packet is being handled; there is noprotocol-specific code in the kernel implementation of thegateway screen.  Either the.I sd_familyfield should be initialized to a specific family before therequest is invoked (indicating that the user process is willingto handle requests for this family only), or it should be set to.PN AF_UNSPEC(indicating that the user process is willing to handle all protocols)..PPThe user-levelprocess examines the packet headers and decides whether or not thepacket should be forwarded.  It communicates this decision to thekernel by filling in the.I sd_actionfield in the.PN screen_datastructure with either.PN SCREEN_ACCEPT ,.PN SCREEN_DROP ,or.PN SCREEN_DROP bit-wise ORed with.PN SCREEN_NOTIFY ;the last choice causes the gateway to drop the packet but sendan error packet to the source host (if this is supported in theprotocol family).The process then passes that structure back to the kernel in anotherinvocation of the.PN SIOCSCREENrequest.  That.I ioctlcall then blocks until a new packet is available, at which point thecycle repeats..PPNote that two actions are being carried outthrough one system call, and that each cycle starts mid-way througha system call.  Thus, the first time a daemon uses this.I ioctlrequest, it has to pass in a no-op decision to complete the first(half) cycle.The kernel matches incoming decisions with pending packets bycomparing both the transaction id.RI ( sd_xid )field, and the user's process id (so one process cannot providedecisions on packets presented to a different process).Decisions must be supplied in first-in, first-out order; decisionssupplied in the wrong order may result in packets being dropped..SH Return ValuesIf an error has occurred, a value of \-1 is returned and.PN errnois set to indicate the error..SH DiagnosticsIn addition to those error codes described for.MS ioctl 2 ,the.PN SIOCSCREENrequest can also return:.TP 20[ENOPROTOOPT]If the screen mode is set to.PN  SCREENMODE_OFF ,the.PN SIOCSCREENrequest is meaningless..TP[EPERM]If an operation reserved for the superuser is attempted bya non-superuser..SH See Alsoscreenmode(8), screend(8), screenstat(8), ioctl(2)