---

Session Handling

---

Detailed Description

One of the most diferencials of LibCGI is its support to sessions, a mechanism that permits the application to keep variables trough the user's session, when he is visiting your website.

Session functions are easy to use and understand, and probably you'll want to take a closer look at cgi_session_save_path() and cgi_session_cookie_name() functions. These functions, let the programmer to set the directory where session files will be saved in the hard disk and the cookie name to the session, respectively. As the CGI is running on the webserver which a common user, it have full access to its respective session file. But the most big problem is that you may have full access to all other session files as well, even from other sites. Yes, that's a big problem, and still other large used scripting languages like PHP does have this kind of problem (using the default installation). So, LibCGI is trying to make a bit harder to a potential attacker to stole session data or even destroy it. Now is possible to store session files in different locations, specified by the programmer ( using cgi_session_save_path() function ), as described in this doc ). And yes, I ( me, LibCGI's author ) knows that there are problems yet, so your opinion is very important. You will find some useful examples under "examples/sessions" directory.

Functions
int	cgi_session_destroy ()
	Destroys the session.
char *	cgi_session_var (const char *var_name)
	Gets session variable's value.
void	cgi_session_cookie_name (const char *cookie_name)
	Defines the name of the cookie that LibCGI will use to store session's ID.
void	cgi_session_save_path (const char *path)
	Defines where session control files will be saved.
int	cgi_session_register_var (const char *name, const char *value)
	Register a variable in the current opened session.
int	cgi_session_alter_var (const char *name, const char *new_value)
	Alter session variable value.
int	cgi_session_var_exists (const char *name)
	Searches for determined session variable.
int	cgi_session_unregister_var (char *name)
	Unregister some session variable.
int	cgi_session_start ()
	Starts a new session.

---

Function Documentation

int cgi_session_alter_var (  const char *    name, const char *    new_value )

Alter session variable value. Change session variable 'name' value to data pointer by 'new_value' Parameters: name  Session variable name to change new_value  New session variable value See also: cgi_session_register_var(), cgi_session_unregister_var()

void cgi_session_cookie_name (  const char *    cookie_name )

Defines the name of the cookie that LibCGI will use to store session's ID. This function works like cgi_session_save_path(). This functionality let you to use different names for each site, but remember, you cannot use multiple session for the same application yet. Parameters: cookie_name  Name of the cookie to create See also: cgi_session_save_path() Note: This function must be called before cgi_session_start()

int cgi_session_destroy (    )

Destroys the session. Destroys the current opened session, including all data. After session_destroy() was called, is not more possible to use session functions before an another call to session_start() Returns: 1 if no errors, 0 if. See also: cgi_session_start cgi_session_error_message

int cgi_session_register_var (  const char *    name, const char *    value )

Register a variable in the current opened session. Note that we are opening and closing the session file every time this function is called... ( I/O ^ 1000000 :-/ ) Parameters: name  Variable name value  Variable value See also: cgi_session_alter_var(), cgi_session_unregister_var()

void cgi_session_save_path (  const char *    path )

Defines where session control files will be saved. If in the your CGI you don't make a call to cgi_session_save_path(), LibCGI will use the default value, which is "/tmp/". To see how to modify the value, see the following example. Just note you need to add '/' at the end of the directory name // your_cgi.c // Set "session_files" directory under your CGI directory as the path // which LibCGI will use to store session files. cgi_session_save_path("session_files/"); Note that using this form, LibCGI will search for "session_files" directory using relative path to your cgi application. For example, if your CGI script is located at /usr/local/httpd/web/your_name/cgi-bin/ directory, and you use the above declaration, the files for the session will be stored at /usr/local/httpd/web/your_name/cgi-bin/session_files directory. Resuming, the path is relative to where your application resides. And remember, LibCGI does not create the directory for you. Parameters: path  Path, relative or absolute See also: cgi_session_cookie_name Note: This function must be called before cgi_session_start()

int cgi_session_start (    )

Starts a new session. This function is responsible for starting and creating a new session. It must be called before any other session function, and every time before any HTML header has sent. See also: session_destroy()

int cgi_session_unregister_var (  char *    name )

Unregister some session variable. Parameters: name  Session variable name to unregister See also: cgi_session_var_exists(), cgi_session_register_var()

char* cgi_session_var (  const char *    var_name )

Gets session variable's value. Parameters: name  Session variable name to get the value Returns: Variable contents if found, NULL if not. See also: cgi_session_var_exists()

int cgi_session_var_exists (  const char *    name )

Searches for determined session variable. Parameters: name  Session variable name to search Returns: 1 if variable is registered, 0 if not See also: cgi_session_var()

---