Main Page Modules Related Pages

# 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()