Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CGI::Session::ExpireSeUsernContributed Perl DocCGI::Session::ExpireSessions(3)

NAME
       "CGI::Session::ExpireSessions" -	Delete expired "CGI::Session"-type
       db-based	and file-based sessions

Synopsis
	       #!/usr/bin/perl

	       use strict;
	       use warnings;

	       use CGI::Session::ExpireSessions;
	       use DBI;

	       # -----------------------------------------------

	       my($dbh)	= DBI -> connect
	       (
		 'dbi:mysql:aussi:127.0.0.1',
		 'root',
		 'pass',
		 {
		   AutoCommit	      => 1,
		   PrintError	      => 0,
		   RaiseError	      => 1,
		   ShowErrorStatement => 1,
		 }
	       );

	       CGI::Session::ExpireSessions -> new(dbh => $dbh,	verbose	=> 1) -> expire_db_sessions();
	       CGI::Session::ExpireSessions -> new(temp_dir => '/tmp', verbose => 1) ->	expire_file_sessions();
	       CGI::Session::ExpireSessions -> new(verbose => 1) -> expire_sessions();

	       # Note: You are strongly	urged to use method expire_sessions() (it requires CGI::Session	V 4 or later),
	       # since it does not eval	the session data, and hence avoids the security	issues of evaling a string
	       # which comes from outside the program. See examples/expire-set.pl, which contains extensive comments.

Description
       "CGI::Session::ExpireSessions" is a pure	Perl module.

       It deletes "CGI::Session"-type sessions which have passed their use-by
       date.

       It works	with "CGI::Session"-type sessions in a database	or in disk
       files, but does not appear to work with "CGI::Session::PureSQL"-type
       sessions.

       The recommended way to use this module is via method
       "expire_sessions()", which requires "CGI::Session" V 4 or later.

       Sessions	can be expired under one of three conditions:

       You deem	the session to be expired as of	now
	   Methods: "expire_db_sessions()" and "expire_file_sessions()"
	       You want	the session to be expired and hence deleted now
	       because it's last access	time is	longer ago than	the time you
	       specify in the call to new, using the delta parameter.

	       That is,	delete the session because the time span, between the
	       "last access" time and now, is greater than delta.

	       In other	words, force sessions to expire.

	       The module has always used this condition to delete sessions.

	   Method: "expire_sessions()"
	       You want	the session to be expired and hence deleted now
	       because it's "last access" time is longer ago than the time you
	       specify in the call to new, using the delta parameter.

       The session has already expired
	   This	section	applies	to all 3 methods: "expire_db_sessions()",
	   "expire_file_sessions()" and	"expire_sessions()".

	   This	condition is new as of V 1.02.

	   You want the	session	to be deleted now because it has already
	   expired.

	   That	is, you	want this module to delete the session,	rather than
	   getting "CGI::Session" to delete it,	when "CGI::Session" would
	   delete the session automatically if you used	"CGI::Session" to
	   retrieve the	session.

	   Note: This condition	assumes	the session's expiration time is
	   defined (it does not	have to	be).

       The file	size is	<= 5 bytes and was accessed more than 'delta' seconds
       ago
	   This	condition is new as of V 1.03.

	   This	section	applies	to method: "expire_file_sessions()".

	   See below for how to	provide	a value	of delta to the	constructor.

	   Old versions	of "CGI::Session" sometimes create a file of size 0
	   bytes, so this test checks for such files, and deletes them if they
	   are old enough.

       Sessions	are deleted if any of these conditions is true.

       Sessions	are deleted from the 'sessions'	table in the database, or from
       the temp	directory, depending on	how you	use "CGI::Session".

Distributions
       This module is available	both as	a Unix-style distro (*.tgz) and	an
       ActiveState-style distro	(*.ppd). The latter is shipped in a *.zip
       file.

       See http://savage.net.au/Perl-modules.html for details.

       See http://savage.net.au/Perl-modules/html/installing-a-module.html for
       help on unpacking and installing	each type of distro.

Security
       For file-based sessions,	method "expire_file_sessions()"	parses the
       contents	of the file, using eval{}, in an attempt to determine the
       access and expiration times recorded within the file.

       So, if you are uneasy about the security	implication of this (as	you
       should be), don't use this method. Use method "expire_sessions()"
       instead.	The latter is a	much more sophisticated	way of expiring
       sessions, but it	does require "CGI::Session" V 4	or later.

Constructor and	initialization
       new(...)	returns	a "CGI::Session::ExpireSessions" object.

       This is the class's contructor.

       Usage: CGI::Session::ExpireSessions -> new().

       This method takes a set of parameters. Only some	of these parameters
       are mandatory.

       For each	parameter, call	method "new()" as new(param_1 => value_1,
       param_2 => value_2, ...).

       Note: As	of V 1.07 of this module, you may call method "set()" to set
       parameters after	calling	method "new()".

       Not only	that, but you may pass into all	of the 3 methods
       "expire_db_sessions()", "expire_file_sessions()"	and
       "expire_sessions()" any of the parameters accepted by "new()", since
       these 3 methods call "set()" if their caller provides parameters.

       Parameters which	can be used with "new()", "set()", or "expire_*()":

       cgi_session_dsn
	   This	is the DSN (Data Source	Name) used by "CGI::Session" to
	   control what	type of	sessions you previously	created	and what type
	   of sessions you now wish to expire.

	   Do not confuse this with the	DSN used by "CGI::Session"'s method
	   find(param_1, \&sub,	{DataSource => other_dsn...}, ...)  when
	   referring to	db-based sessions.

	   Method "expire_sessions()" is the only method in this module	which
	   uses	this parameter.

	   So, when you	call "expire_sessions()", this parameter -
	   cgi_session_dsn - determines	the set	of sessions processed by, and
	   possibly expired by,	the call to "expire_sessions()".

	   The default value is	undef, which means "CGI::Session" defaults to
	   file-based sessions.

	   This	parameter is optional for file-based sessions, and mandatory
	   for db-based	sessions.

       dbh This	is a database handle for the database containing the table
	   'sessions'.

	   Either this parameter is mandatory, or the temp_dir parameter is
	   mandatory.

       delta
	   Methods: "expire_db_sessions()" and "expire_file_sessions()"
	       This is the number of seconds since the "last access" to	the
	       session,	which determines whether or not	the session will be
	       expired.

	   Method: "expire_sessions()"
	       This is the number of seconds since the "last access" time of
	       the session, which determines whether or	not the	session	will
	       be expired.

	   The default value is	2 * 24 * 60 * 60, which	is the number of
	   seconds in 2	days.

	   By default, then, sessions which were last accessed more than 2
	   days	ago are	expired.

	   This	parameter is optional.

       dsn_args
	   If your cgi_session_dsn uses	file-based storage, then this hashref
	   might contain keys such as:

		   {
			   Directory =>	Value 1,
			   NoFlock   =>	Value 2,
			   UMask     =>	Value 3
		   }

	   If your cgi_session_dsn uses	db-based storage, then this hashref
	   contains (up	to) 3 keys, and	looks like:

		   {
			   DataSource => Value 1,
			   User	      => Value 2,
			   Password   => Value 3
		   }

	   These 3 form	the DSN, username and password used by DBI to control
	   access to your database server, and hence are only relevant when
	   using db-based sessions.

	   Method "expire_sessions()" is the only method in this module	which
	   uses	the parameter dsn_args.

	   The default value for this parameter	is undef.

	   These parameters are	optional for file-based	sessions, and
	   mandatory for db-based sessions.

       table_name
	   This	is the name of the database table used to hold the sessions.

	   The default value is	'sessions'.

	   This	parameter is optional.

       temp_dir
	   This	is the name of the temp	directory where	you store
	   CGI::Session-type session files.

	   The default value is	'/tmp'.

	   Either this parameter is mandatory, or the dbh parameter is
	   mandatory.

       time
	   The session's "last access" time is subtracted from the value of
	   this	parameter, and if the result is	greater	than or	equal to the
	   value of parameter 'delta', then the	session	is expired.

	   Method "expire_sessions()" is the only method in this module	which
	   uses	this parameter.

	   The default value is	obtained by calling time().

	   This	parameter is optional.

       verbose
	   This	is a integer, 0	or 1, which - when set to 1 - causes progress
	   messages to be written to STDOUT.

	   The default value is	0.

	   This	parameter is optional.

Method:	expire_db_sessions()
       Returns nothing.

       This method uses	the dbh	parameter passed to "new()" to delete
       database-type sessions.

Method:	expire_file_sessions()
       Returns nothing.

       This method uses	the temp_dir parameter passed to "new()" to delete
       file-type sessions.

Method:	expire_sessions()
       Return value:

       undef
	   Returns undef if your version of "CGI::Session" does	not support
	   method "find()".

	   Also, returns undef when "CGI::Session"'s method "find()" failed
	   for some reason.

       1   Returns 1 when "find()" succeeds.

       Returns the result of calling CGI::Session's method find(), which will
       be undef	for some sort of failure, and 1	for success.

       This method handles both	file-based and db-based	sessions.

Example	code
       See the examples/ directory in the distro.

       There are 2 demo	programs: expire-sessions.pl and expire-set.pl.

Author
       "CGI::Session::ExpireSessions" was written by Ron Savage
       _ron@savage.net.au_ in 2004.

       Home page: http://savage.net.au/index.html

Copyright
       Australian copyright (c)	2004, Ron Savage.	All Programs of	mine
       are 'OSI	Certified Open Source Software';      you can redistribute
       them and/or modify them under the terms of      The Artistic License, a
       copy of which is	available at:
	    http://www.opensource.org/licenses/index.html

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 615:
	   Expected text after =item, not a number

perl v5.32.1			  2010-08-24   CGI::Session::ExpireSessions(3)

NAME | Synopsis | Description | Distributions | Security | Constructor and initialization | Method: expire_db_sessions() | Method: expire_file_sessions() | Method: expire_sessions() | Example code | Author | Copyright | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CGI::Session::ExpireSessions&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help