ncgi man page on Ubuntu

Man page or keyword search:  
man Server   6591 pages
apropos Keyword Search (all sections)
Output format
Ubuntu logo
[printable version]

ncgi(3tcl)			  CGI Support			    ncgi(3tcl)

______________________________________________________________________________

NAME
       ncgi - Procedures to manipulate CGI values.

SYNOPSIS
       package require Tcl  8.2

       package require ncgi  ?1.3?

       ::ncgi::cookie cookie

       ::ncgi::decode str

       ::ncgi::empty name

       ::ncgi::exists name

       ::ncgi::encode string

       ::ncgi::header ?type? args

       ::ncgi::import cginame ?tclname?

       ::ncgi::importAll args

       ::ncgi::importFile cmd cginame ?filename?

       ::ncgi::input ?fakeinput? ?fakecookie?

       ::ncgi::multipart type query

       ::ncgi::nvlist

       ::ncgi::names

       ::ncgi::parse

       ::ncgi::parseMimeValue value

       ::ncgi::query

       ::ncgi::redirect url

       ::ncgi::reset query type

       ::ncgi::setCookie args

       ::ncgi::setDefaultValue key defvalue

       ::ncgi::setDefaultValueList key defvaluelist

       ::ncgi::setValue key value

       ::ncgi::setValueList key valuelist

       ::ncgi::type

       ::ncgi::urlStub ?url?

       ::ncgi::value key ?default?

       ::ncgi::valueList key ?default?

_________________________________________________________________

DESCRIPTION
       The  ncgi  package provides commands that manipulate CGI values.	 These
       are values that come from Web forms and are  processed  either  by  CGI
       scripts	or  web pages with embedded Tcl code.  Use the ncgi package to
       query these values, set and get cookies, and encode and decode www-url-
       encoded values.

       In  the	simplest case, a CGI script first calls ::ncgi::parse and then
       calls ::ncgi::value to get different form values.  If a	CGI  value  is
       repeated,  you  should  use  ::ncgi::valueList to get back the complete
       list of values.

       An alternative to ::ncgi::parse is ::ncgi::input, which	has  semantics
       similar	to  Don	 Libes'	 cgi_input procedure.  ::ncgi::input restricts
       repeated CGI values to have names that end with "List".	In this	 case,
       ::ncgi::value   will   return   the   complete	list  of  values,  and
       ::ncgi::input will raise errors if it find repeated form elements with‐
       out the right name.

       The  ::ncgi::reset procedure can be used in test suites and Web servers
       to initialize the source of the CGI values.  Otherwise the  values  are
       read in from the CGI environment.

       The complete set of procedures is described below.

       ::ncgi::cookie cookie
	      Return a list of values for cookie, if any.  It is possible that
	      more than one cookie with the same name can be present, so  this
	      procedure returns a list.

       ::ncgi::decode str
	      Decode  strings  in  www-url-encoding,  which represents special
	      characters with a %xx sequence, where xx is the  character  code
	      in hex.

       ::ncgi::empty name
	      Returns  1  if  the  CGI variable name is not present or has the
	      empty string as its value.

       ::ncgi::exists name
	      The return value is a boolean. It returns 0 if the CGI  variable
	      name is not present, and 1 otherwise.

       ::ncgi::encode string
	      Encode string into www-url-encoded format.

       ::ncgi::header ?type? args
	      Output the CGI header to standard output.	 This emits a Content-
	      Type: header and additional headers based on args,  which	 is  a
	      list  of	header	names  and header values. The type defaults to
	      "text/html".

       ::ncgi::import cginame ?tclname?
	      This creates a variable in the current scope with the  value  of
	      the  CGI variable cginame.  The name of the variable is tclname,
	      or cginame if tclname is empty (default).

       ::ncgi::importAll args
	      This imports several CGI variables as Tcl variables.  If args is
	      empty,  then  every  CGI	value is imported.  Otherwise each CGI
	      variable listed in args is imported.

       ::ncgi::importFile cmd cginame ?filename?
	      This provides information about an uploaded  file	 from  a  form
	      input  field  of type file with name cginame.  cmd can be one of
	      -server -client, -type or -data.

	      -client cginame
		     returns the filename as sent by the client.

	      -type cginame
		     returns the mime type of the uploaded file.

	      -data cginame
		     returns the contents of the file.

	      -server cginame filename
		     writes the file contents to a local  temporary  file  (or
		     filename  if  supplied) and returns the name of the file.
		     The caller is responsible for deleting  this  file	 after
		     use.

       ::ncgi::input ?fakeinput? ?fakecookie?
	      This  reads and decodes the CGI values from the environment.  It
	      restricts repeated form values to	 have  a  trailing  "List"  in
	      their  name.   The  CGI  values  are  obtained  later  with  the
	      ::ncgi::value procedure.

       ::ncgi::multipart type query
	      This procedure parses a multipart/form-data query.  This is used
	      by  ::ncgi::nvlist and not normally called directly.  It returns
	      an alternating list of names and structured values.  Each struc‐
	      ture value is in turn a list of two elements.  The first element
	      is meta-data from the multipart/form-data structure.  The second
	      element  is  the	form value.  If you use ::ncgi::value you just
	      get the form value.  If you use ::ncgi::valueList	 you  get  the
	      structured value with meta data and the value.

	      The  type	 is  the  whole Content-Type, including the parameters
	      like boundary.  This returns a list of  names  and  values  that
	      describe	the  multipart	data.	The  values  are a nested list
	      structure that has some descriptive information first,  and  the
	      actual  form  value second.  The descriptive information is list
	      of header names and values that describe the content.

       ::ncgi::nvlist
	      This returns all the query data as a name, value list.   In  the
	      case  of	multipart/form-data,  the  values  are	structured  as
	      described in ::ncgi::multipart.

       ::ncgi::names
	      This returns all names found in  the  query  data,  as  a	 list.
	      ::ncgi::multipart.

       ::ncgi::parse
	      This reads and decodes the CGI values from the environment.  The
	      CGI values are obtained later with the ::ncgi::value  procedure.
	      IF  a  CGI  value	 is repeated, then you should use ::ncgi::val‐
	      ueList to get the complete list of values.

       ::ncgi::parseMimeValue value
	      This decodes the Content-Type and other MIME headers  that  have
	      the form of "primary value; param=val; p2=v2" It returns a list,
	      where the first element is the primary  value,  and  the	second
	      element is a list of parameter names and values.

       ::ncgi::query
	      This returns the raw query data.

       ::ncgi::redirect url
	      Generate	a  response  that  causes  a  302  redirect by the Web
	      server.  The url is the new URL that is the target of the	 redi‐
	      rect.   The  URL	will  be qualified with the current server and
	      current directory, if necessary, to convert it into a full URL.

       ::ncgi::reset query type
	      Set the query data and Content-Type for the current CGI session.
	      This  is used by the test suite and by Web servers to initialize
	      the ncgi module so it does not try to read standard input or use
	      environment variables to get its data.  If neither query or type
	      are specified, then the ncgi module will look  in	 the  standard
	      CGI environment for its data.

       ::ncgi::setCookie args
	      Set  a  cookie value that will be returned as part of the reply.
	      This must be done before ::ncgi::header or  ::ncgi::redirect  is
	      called  in  order	 for  the cookie to be returned properly.  The
	      args are a set of flags and values:

	      -name name

	      -value value

	      -expires date

	      -path path restriction

	      -domain domain restriction

       ::ncgi::setDefaultValue key defvalue
	      Set a CGI value if it does not  already  exists.	 This  affects
	      future   calls   to  ::ncgi::value  (but	not  future  calls  to
	      ::ncgi::nvlist).	If the CGI value already is present, then this
	      procedure has no side effects.

       ::ncgi::setDefaultValueList key defvaluelist
	      Like  ::ncgi::setDefaultValue  except that the value already has
	      list structure to represent  multiple  checkboxes	 or  a	multi-
	      selection.

       ::ncgi::setValue key value
	      Set  a  CGI  value,  overriding  whatever was present in the CGI
	      environment already.  This affects future calls to ::ncgi::value
	      (but not future calls to ::ncgi::nvlist).

       ::ncgi::setValueList key valuelist
	      Like  ::ncgi::setValue  except  that  the value already has list
	      structure to represent multiple checkboxes or a multi-selection.

       ::ncgi::type
	      Returns the Content-Type of the current CGI values.

       ::ncgi::urlStub ?url?
	      Returns the current URL, but without the protocol,  server,  and
	      port.  If url is specified, then it defines the URL for the cur‐
	      rent session.  That value will be returned by  future  calls  to
	      ::ncgi::urlStub

       ::ncgi::value key ?default?
	      Return the CGI value identified by key.  If the CGI value is not
	      present, then the default value is returned instead. This	 value
	      defaults to the empty string.

	      If  the form value key is repeated, then there are two cases: if
	      ::ncgi::parse was called, then ::ncgi::value  only  returns  the
	      first  value  associated with key.  If ::ncgi::input was called,
	      then ::ncgi::value returns a Tcl list value and key must end  in
	      "List"  (e.g.,  "skuList").  In the case of multipart/form-data,
	      this procedure just returns the value of the form	 element.   If
	      you want the meta-data associated with each form value, then use
	      ::ncgi::valueList.

       ::ncgi::valueList key ?default?
	      Like ::ncgi::value, but this always returns  a  list  of	values
	      (even  if	 there	is  only  one  value).	 In the case of multi‐
	      part/form-data, this procedure returns a list of	two  elements.
	      The first element is meta-data in the form of a parameter, value
	      list.  The second element is the form value.

EXAMPLES
       Uploading a file

       HTML:
       <html>
       <form action="/cgi-bin/upload.cgi" method="POST" enctype="multipart/form-data">
       Path: <input type="file" name="filedata"><br>
       Name: <input type="text" name="filedesc"><br>
       <input type="submit">
       </form>
       </html>

       TCL: upload.cgi
       #!/usr/local/bin/tclsh

       ::ncgi::parse
       set filedata [::ncgi::value filedata]
       set filedesc [::ncgi::value filedesc]

       puts "<html> File uploaded at <a href=\"/images/$filedesc\">$filedesc</a> </html>"

       set filename /www/images/$filedesc

       set fh [open $filename w]
       puts -nonewline $fh $filedata
       close $fh

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs  and  other	 problems.  Please report such in the category ncgi of
       the	   Tcllib	  SF	     Trackers	       [http://source‐
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.

SEE ALSO
       html

KEYWORDS
       CGI, cookie, form, html

CATEGORY
       CGI programming

ncgi				      1.3			    ncgi(3tcl)
[top]

List of man pages available for Ubuntu

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net