data/TWiki/CGISessionDriverFileDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
---+ Package ==
colas@0
     2
colas@0
     3
%TOC%
colas@0
     4
=head1 NAME
colas@0
     5
colas@0
     6
CGI::Session::Driver::file - Default CGI::Session driver
colas@0
     7
colas@0
     8
=head1 SYNOPSIS
colas@0
     9
colas@0
    10
    $s = new CGI::Session();
colas@0
    11
    $s = new CGI::Session("driver:file", $sid);
colas@0
    12
    $s = new CGI::Session("driver:file", $sid, {Directory=>'/tmp'});
colas@0
    13
colas@0
    14
colas@0
    15
=head1 DESCRIPTION
colas@0
    16
colas@0
    17
When CGI::Session object is created without explicitly setting I<driver>, I<file> will be assumed.
colas@0
    18
I<file> - driver will store session data in plain files, where each session will be stored in a separate
colas@0
    19
file.
colas@0
    20
colas@0
    21
Naming conventions of session files are defined by C<$CGI::Session::Driver::file::FileName> global variable. 
colas@0
    22
Default value of this variable is I<cgisess_%s>, where %s will be replaced with respective session ID. Should
colas@0
    23
you wish to set your own FileName template, do so before requesting for session object:
colas@0
    24
colas@0
    25
    $CGI::Session::Driver::file::FileName = "%s.dat";
colas@0
    26
    $s = new CGI::Session();
colas@0
    27
colas@0
    28
For backwards compatibility with 3.x, you can also use the variable name
colas@0
    29
C<$CGI::Session::File::FileName>, which will override the one above. 
colas@0
    30
colas@0
    31
=head2 DRIVER ARGUMENTS
colas@0
    32
colas@0
    33
If you wish to specify a session directory, use the B<Directory> option, which denotes location of the directory 
colas@0
    34
where session ids are to be kept. If B<Directory> is not set, defaults to whatever File::Spec->tmpdir() returns. 
colas@0
    35
So all the three lines in the SYNOPSIS section of this manual produce the same result on a UNIX machine.
colas@0
    36
colas@0
    37
If specified B<Directory> does not exist, all necessary directory hierarchy will be created.
colas@0
    38
colas@0
    39
By default, sessions are created with a umask of 0660. If you wish to change the umask for a session, pass
colas@0
    40
a B<UMask> option with an octal representation of the umask you would like for said session. 
colas@0
    41
colas@0
    42
=head1 NOTES
colas@0
    43
colas@0
    44
If your OS doesn't support flock, you should understand the risks of going without locking the session files. Since
colas@0
    45
sessions tend to be used in environments where race conditions may occur due to concurrent access of files by 
colas@0
    46
different processes, locking tends to be seen as a good and very necessary thing. If you still want to use this 
colas@0
    47
driver but don't want flock, set C<$CGI::Session::Driver::file::NoFlock> to 1 or pass C<< NoFlock => 1 >> and this 
colas@0
    48
driver will operate without locks.
colas@0
    49
colas@0
    50
=head1 LICENSING
colas@0
    51
colas@0
    52
For support and licensing see L<CGI::Session|CGI::Session>
colas@0
    53