func_env.c

/*
 * Asterisk -- An open source telephony toolkit.
 *
 * Copyright (C) 1999 - 2010, Digium, Inc.
 *
 * See http://www.asterisk.org for more information about
 * the Asterisk project. Please do not directly contact
 * any of the maintainers of this project for assistance;
 * the project provides a web site, mailing lists and IRC
 * channels for your use.
 *
 * This program is free software, distributed under the terms of
 * the GNU General Public License Version 2. See the LICENSE file
 * at the top of the source tree.
 */

/*! \file
 *
 * \brief Environment related dialplan functions
 *
 * \ingroup functions
 */

/*** MODULEINFO
	<support_level>core</support_level>
 ***/

#include "asterisk.h"

#include <sys/stat.h>   /* stat(2) */
#include <libgen.h>     /* dirname and basename */

#include "asterisk/module.h"
#include "asterisk/channel.h"
#include "asterisk/pbx.h"
#include "asterisk/utils.h"
#include "asterisk/app.h"
#include "asterisk/file.h"

/*** DOCUMENTATION
	<function name="ENV" language="en_US">
		<synopsis>
			Gets or sets the environment variable specified.
		</synopsis>
		<syntax>
			<parameter name="varname" required="true">
				<para>Environment variable name</para>
			</parameter>
		</syntax>
		<description>
			<para>Variables starting with <literal>AST_</literal> are reserved to the system and may not be set.</para>
			<para>Additionally, the following system variables are available as special built-in dialplan variables.
			These variables cannot be set or modified and are read-only.</para>
			<variablelist>
				<variable name="EPOCH">
					<para>Current unix style epoch</para>
				</variable>
				<variable name="SYSTEMNAME">
					<para>value of the <literal>systemname</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTCACHEDIR">
					<para>value of the <literal>astcachedir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTETCDIR">
					<para>value of the <literal>astetcdir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTMODDIR">
					<para>value of the <literal>astmoddir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTVARLIBDIR">
					<para>value of the <literal>astvarlib</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTDBDIR">
					<para>value of the <literal>astdbdir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTKEYDIR">
					<para>value of the <literal>astkeydir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTDATADIR">
					<para>value of the <literal>astdatadir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTAGIDIR">
					<para>value of the <literal>astagidir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTSPOOLDIR">
					<para>value of the <literal>astspooldir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTRUNDIR">
					<para>value of the <literal>astrundir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTLOGDIR">
					<para>value of the <literal>astlogdir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ASTSBINDIR">
					<para>value of the <literal>astsbindir</literal> option from <literal>asterisk.conf</literal></para>
				</variable>
				<variable name="ENTITYID">
					<para>Global Entity ID set automatically, or from <literal>asterisk.conf</literal></para>
				</variable>
			</variablelist>
		</description>
	</function>
	<function name="STAT" language="en_US">
		<synopsis>
			Does a check on the specified file.
		</synopsis>
		<syntax>
			<parameter name="flag" required="true">
				<para>Flag may be one of the following:</para>
				<para>d - Checks if the file is a directory.</para>
				<para>e - Checks if the file exists.</para>
				<para>f - Checks if the file is a regular file.</para>
				<para>m - Returns the file mode (in octal)</para>
				<para>s - Returns the size (in bytes) of the file</para>
				<para>A - Returns the epoch at which the file was last accessed.</para>
				<para>C - Returns the epoch at which the inode was last changed.</para>
				<para>M - Returns the epoch at which the file was last modified.</para>
			</parameter>
			<parameter name="filename" required="true" />
		</syntax>
		<description>
			<note>
				<para>If <literal>live_dangerously</literal> in <literal>asterisk.conf</literal>
				is set to <literal>no</literal>, this function can only be executed from the
				dialplan, and not directly from external protocols.</para>
			</note>
		</description>
	</function>
	<function name="FILE" language="en_US">
		<synopsis>
			Read or write text file.
		</synopsis>
		<syntax>
			<parameter name="filename" required="true" />
			<parameter name="offset">
				<para>Maybe specified as any number. If negative, <replaceable>offset</replaceable> specifies the number
				of bytes back from the end of the file.</para>
			</parameter>
			<parameter name="length">
				<para>If specified, will limit the length of the data read to that size. If negative,
				trims <replaceable>length</replaceable> bytes from the end of the file.</para>
			</parameter>
			<parameter name="options">
				<optionlist>
					<option name="l">
						<para>Line mode:  offset and length are assumed to be
						measured in lines, instead of byte offsets.</para>
					</option>
					<option name="a">
						<para>In write mode only, the append option is used to
						append to the end of the file, instead of overwriting
						the existing file.</para>
					</option>
					<option name="d">
						<para>In write mode and line mode only, this option does
						not automatically append a newline string to the end of
						a value.  This is useful for deleting lines, instead of
						setting them to blank.</para>
					</option>
				</optionlist>
			</parameter>
			<parameter name="format">
				<para>The <replaceable>format</replaceable> parameter may be
				used to delimit the type of line terminators in line mode.</para>
				<optionlist>
					<option name="u">
						<para>Unix newline format.</para>
					</option>
					<option name="d">
						<para>DOS newline format.</para>
					</option>
					<option name="m">
						<para>Macintosh newline format.</para>
					</option>
				</optionlist>
			</parameter>
		</syntax>
		<description>
			<para>Read and write text file in character and line mode.</para>
			<para>Examples:</para>
			<para>Read mode (byte):</para>
			<example title="Reads the entire content of the file">
			same => n,Set(foo=${FILE(/tmp/test.txt)})
			</example>
			<example title="Reads from the 11th byte to the end of the file (i.e. skips the first 10)">
			same => n,Set(foo=${FILE(/tmp/test.txt,10)})
			</example>
			<example title="Reads from the 11th to 20th byte in the file (i.e. skip the first 10, then read 10 bytes)">
			same => n,Set(foo=${FILE(/tmp/test.txt,10,10)})
			</example>
			<para>Read mode (line):</para>
			<example title="Reads the 3rd line of the file">
			same => n,Set(foo=${FILE(/tmp/test.txt,3,1,l)})
			</example>
			<example title="Reads the 3rd and 4th lines of the file">
			same => n,Set(foo=${FILE(/tmp/test.txt,3,2,l)})
			</example>
			<example title="Reads from the third line to the end of the file">
			same => n,Set(foo=${FILE(/tmp/test.txt,3,,l)})
			</example>