This is Info file octave.info, produced by Makeinfo version 1.67 from the input file /ade-src/fsf/octave/doc/interpreter/octave.texi. START-INFO-DIR-ENTRY * Octave: (octave). Interactive language for numerical computations. END-INFO-DIR-ENTRY Copyright (C) 1996 John W. Eaton. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.  File: octave.info, Node: Famous Matrices, Prev: Special Utility Matrices, Up: Special Matrices Famous Matrices =============== The following functions return famous matrix forms. - Function File: hadamard (K) Return the Hadamard matrix of order n = 2^k. - Function File: hankel (C, R) Return the Hankel matrix constructed given the first column C, and (optionally) the last row R. If the last element of C is not the same as the first element of R, the last element of C is used. If the second argument is omitted, the last row is taken to be the same as the first column. A Hankel matrix formed from an m-vector C, and an n-vector R, has the elements H (i, j) = c (i+j-1), i+j-1 <= m; H (i, j) = r (i+j-m), otherwise - Function File: hilb (N) Return the Hilbert matrix of order N. The i, j element of a Hilbert matrix is defined as H (i, j) = 1 / (i + j - 1) - Function File: invhilb (N) Return the inverse of a Hilbert matrix of order N. This is exact. Compare with the numerical calculation of `inverse (hilb (n))', which suffers from the ill-conditioning of the Hilbert matrix, and the finite precision of your computer's floating point arithmetic. - Function File: toeplitz (C, R) Return the Toeplitz matrix constructed given the first column C, and (optionally) the first row R. If the first element of C is not the same as the first element of R, the first element of C is used. If the second argument is omitted, the first row is taken to be the same as the first column. A square Toeplitz matrix has the form c(0) r(1) r(2) ... r(n) c(1) c(0) r(1) r(n-1) c(2) c(1) c(0) r(n-2) . . . . . . c(n) c(n-1) c(n-2) ... c(0) - Function File: vander (C) Return the Vandermonde matrix whose next to last column is C. A Vandermonde matrix has the form c(0)^n ... c(0)^2 c(0) 1 c(1)^n ... c(1)^2 c(1) 1 . . . . . . . . . . . . c(n)^n ... c(n)^2 c(n) 1  File: octave.info, Node: Matrix Manipulation, Next: String Functions, Prev: Special Matrices, Up: Top Matrix Manipulation ******************* There are a number of functions available for checking to see if the elements of a matrix meet some condition, and for rearranging the elements of a matrix. For example, Octave can easily tell you if all the elements of a matrix are finite, or are less than some specified value. Octave can also rotate the elements, extract the upper- or lower-triangular parts, or sort the columns of a matrix. * Menu: * Finding Elements and Checking Conditions:: * Rearranging Matrices::  File: octave.info, Node: Finding Elements and Checking Conditions, Next: Rearranging Matrices, Prev: Matrix Manipulation, Up: Matrix Manipulation Finding Elements and Checking Conditions ======================================== The functions `any' and `all' are useful for determining whether any or all of the elements of a matrix satisfy some condition. The `find' function is also useful in determining which elements of a matrix meet a specified condition. - Built-in Function: any (X) For a vector argument, return 1 if any element of the vector is nonzero. For a matrix argument, return a row vector of ones and zeros with each element indicating whether any of the elements of the corresponding column of the matrix are nonzero. For example, any (eye (2, 4)) => [ 1, 1, 0, 0 ] To see if any of the elements of a matrix are nonzero, you can use a statement like any (any (a)) - Built-in Function: all (X) The function `all' behaves like the function `any', except that it returns true only if all the elements of a vector, or all the elements in a column of a matrix, are nonzero. Since the comparison operators (*note Comparison Ops::.) return matrices of ones and zeros, it is easy to test a matrix for many things, not just whether the elements are nonzero. For example, all (all (rand (5) < 0.9)) => 0 tests a random 5 by 5 matrix to see if all of it's elements are less than 0.9. Note that in conditional contexts (like the test clause of `if' and `while' statements) Octave treats the test as if you had typed `all (all (condition))'. - Function File: [ERRORCODE, Y_1, ...] = common_size (X_1, ...) Determine if all input arguments are either scalar or of common size. If so, errorcode is zero, and Y_I is a matrix of the common size with all entries equal to X_I if this is a scalar or X_I otherwise. If the inputs cannot be brought to a common size, errorcode is 1, and Y_I is X_I. For example, [errorcode, a, b] = common_size ([1 2; 3 4], 5) => errorcode = 0 => a = [1 2, 3 4] => b = [5 5; 5 5] This is useful for implementing functions where arguments can either be scalars or of common size. - Function File: diff (X, K) If X is a vector of length N, `diff (X)' is the vector of first differences X(2) - X(1), ..., X(n) - X(n-1). If X is a matrix, `diff (X)' is the matrix of column differences. The second argument is optional. If supplied, `diff (X, K)', where K is a nonnegative integer, returns the K-th differences. - Mapping Function: isinf (X) Return 1 for elements of X that are infinite and zero otherwise. For example, isinf ([13, Inf, NaN]) => [ 0, 1, 0 ] - Mapping Function: isnan (X) Return 1 for elements of X that are NaN values and zero otherwise. For example, isnan ([13, Inf, NaN]) => [ 0, 0, 1 ] - Mapping Function: finite (X) Return 1 for elements of X that are NaN values and zero otherwise. For example, finite ([13, Inf, NaN]) => [ 1, 0, 0 ] - Loadable Function: find (X) The function `find' returns a vector of indices of nonzero elements of a matrix. To obtain a single index for each matrix element, Octave pretends that the columns of a matrix form one long vector (like Fortran arrays are stored). For example, find (eye (2)) => [ 1; 4 ] If two outputs are requested, `find' returns the row and column indices of nonzero elements of a matrix. For example, [i, j] = find (2 * eye (2)) => i = [ 1; 2 ] => j = [ 1; 2 ] If three outputs are requested, `find' also returns a vector containing the the nonzero values. For example, [i, j, v] = find (3 * eye (2)) => i = [ 1; 2 ] => j = [ 1; 2 ] => v = [ 3; 3 ]  File: octave.info, Node: Rearranging Matrices, Prev: Finding Elements and Checking Conditions, Up: Matrix Manipulation Rearranging Matrices ==================== - Function File: fliplr (X) Return a copy of X with the order of the columns reversed. For example, fliplr ([1, 2; 3, 4]) => 2 1 4 3 - Function File: flipud (X) Return a copy of X with the order of the rows reversed. For example, flipud ([1, 2; 3, 4]) => 3 4 1 2 - Function File: rot90 (X, N) Returns a copy of X with the elements rotated counterclockwise in 90-degree increments. The second argument is optional, and specifies how many 90-degree rotations are to be applied (the default value is 1). Negative values of N rotate the matrix in a clockwise direction. For example, rot90 ([1, 2; 3, 4], -1) => 3 1 4 2 rotates the given matrix clockwise by 90 degrees. The following are all equivalent statements: rot90 ([1, 2; 3, 4], -1) rot90 ([1, 2; 3, 4], 3) rot90 ([1, 2; 3, 4], 7) - Function File: reshape (A, M, N) Return a matrix with M rows and N columns whose elements are taken from the matrix A. To decide how to order the elements, Octave pretends that the elements of a matrix are stored in column-major order (like Fortran arrays are stored). For example, reshape ([1, 2, 3, 4], 2, 2) => 1 3 2 4 If the variable `do_fortran_indexing' is nonzero, the `reshape' function is equivalent to retval = zeros (m, n); retval (:) = a; but it is somewhat less cryptic to use `reshape' instead of the colon operator. Note that the total number of elements in the original matrix must match the total number of elements in the new matrix. - Function File: shift (X, B) If X is a vector, perform a circular shift of length B of the elements of X. If X is a matrix, do the same for each column of X. - Loadable Function: [s, i] = sort (X) Returns a copy of X with the elements elements arranged in increasing order. For matrices, `sort' orders the elements in each column. For example, sort ([1, 2; 2, 3; 3, 1]) => 1 1 2 2 3 3 The `sort' function may also be used to produce a matrix containing the original row indices of the elements in the sorted matrix. For example, [s, i] = sort ([1, 2; 2, 3; 3, 1]) => s = 1 1 2 2 3 3 => i = 1 3 2 1 3 2 Since the `sort' function does not allow sort keys to be specified, so it can't be used to order the rows of a matrix according to the values of the elements in various columns(1) in a single call. Using the second output, however, it is possible to sort all rows based on the values in a given column. Here's an example that sorts the rows of a matrix based on the values in the second column. a = [1, 2; 2, 3; 3, 1]; [s, i] = sort (a (:, 2)); a (i, :) => 3 1 1 2 2 3 - Function File: tril (A, K) - Function File: triu (A, K) Return a new matrix form by extracting extract the lower (`tril') or upper (`triu') triangular part of the matrix A, and setting all other elements to zero. The second argument is optional, and specifies how many diagonals above or below the main diagonal should also be set to zero. The default value of K is zero, so that `triu' and `tril' normally include the main diagonal as part of the result matrix. If the value of K is negative, additional elements above (for `tril') or below (for `triu') the main diagonal are also selected. The absolute value of K must not be greater than the number of sub- or super-diagonals. For example, tril (ones (3), -1) => 0 0 0 1 0 0 1 1 0 and tril (ones (3), 1) => 1 1 0 1 1 1 1 1 1 - Function File: vec (X) For a matrix X, returns the vector obtained by stacking the columns of X one above the other. See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics. - Function File: vech (X) For a square matrix X, returns the vector obtained from X by eliminating all supradiagonal elements and stacking the result one column above the other. See Magnus and Neudecker (1988), Matrix differential calculus with applications in statistics and econometrics. ---------- Footnotes ---------- (1) For example, to first sort based on the values in column 1, and then, for any values that are repeated in column 1, sort based on the values found in column 2, etc.  File: octave.info, Node: String Functions, Next: System Utilities, Prev: Matrix Manipulation, Up: Top String Functions **************** - Function File: strcmp (S1, S2) Compares two strings, returning 1 if they are the same, and 0 otherwise. *Note: For compatibility with MATLAB, Octave's strcmp function returns 1 if the strings are equal, and 0 otherwise. This is just the opposite of the corresponding C library function.* - Function File: int2str (N) - Function File: num2str (X) Convert a number to a string. These functions are not very flexible, but are provided for compatibility with MATLAB. For better control over the results, use `sprintf' (*note Formatted Output::.). - Built-in Function: setstr (X) Convert a matrix to a string. Each element of the matrix is converted to the corresponding ASCII character. For example, setstr ([97, 98, 99]) creates the string abc - Built-in Variable: implicit_str_to_num_ok If the value of `implicit_str_to_num_ok' is nonzero, implicit conversions of strings to their numeric ASCII equivalents are allowed. Otherwise, an error message is printed and control is returned to the top level. The default value is 0. - Built-in Function: undo_string_escapes (S) Converts special characters in strings back to their escaped forms. For example, the expression bell = "\a"; assigns the value of the alert character (control-g, ASCII code 7) to the string variable BELL. If this string is printed, the system will ring the terminal bell (if it is possible). This is normally the desired outcome. However, sometimes it is useful to be able to print the original representation of the string, with the special characters replaced by their escape sequences. For example, octave:13> undo_string_escapes (bell) ans = \a replaces the unprintable alert character with its printable representation. *Note String Constants::, for a description of string escapes. - Function File: bin2dec (S) Given a binary number represented as a string of zeros and ones, returns the corresponding decimal number. For example, bin2dec ("1110") => 14 - Function File: blanks (varn) Returns a string of N blanks. - Function File: deblank (S) Removes the trailing blanks from the string S. - Function File: dec2bin (N) Given a nonnegative integer, returns the corresponding binary number as a string of ones and zeros. For example, dec2bin (14) => "1110" - Function File: dec2hex (N) Given a nonnegative integer, returns the corresponding hexadecimal number as a string. For example, dec2hex (2748) => "abc" - Function File: findstr (S, T, OVERLAP) Returns the vector of all positions in the longer of the two strings S and T where an occurence of the shorter of the two starts. If the optional argument OVERLAP is nonzero, the returned vector can include overlapping positions (this is the default). For example, findstr ("ababab", "a") => [1 3 5] findstr ("abababa", "aba", 0) => [1, 5] - Function File: hex2dec (S) Given a hexadecimal number represented as a string, returns the corresponding decimal number. For example, hex2dec ("12B") => 299 hex2dec ("12b") => 299 - Function File: index (S, T) Returns the position of the first occurence of the string T in the string S, or 0 if no occurence is found. For example, index ("Teststring", "t") => 4 *Note:* This function does not work for arrays of strings. - Function File: rindex (S, T) Returns the position of the last occurence of the string T in the string S, or 0 if no occurence is found. For example, rindex ("Teststring", "t") => 6 *Note:* This function does not work for arrays of strings. - Function File: split (S, T) Divides the string S into pieces separated by T, returning the result in a string array (padded with blanks to form a valid matrix). For example, split ("Test string", "t") => Tes s ring - Function File: str2num (S) Convert the string S to a number. - Function File: str2mat (S_1, ..., S_N) Returns a matrix containing the strings S_1, ..., S_N as its rows. Each string is padded with blanks in order to form a valid matrix. *Note:* This function is modelled after MATLAB. In Octave, you can create a matrix of strings by `[S_1; ...; S_N]'. - Built-in Variable: string_fill_char - Function File: strrep (S, X, Y) Replaces all occurences of the substring X of the string S with the string Y. For example, strrep ("This is a test string", "is", "&%$") => Th&%$ &%$ a test string - Function File: substr (S, BEG, LEN) Returns the substring of S which starts at character number BEG and is LEN characters long. For example, substr ("This is a test string", 6, 9) => is a test *Note:* This function is patterned after AWK. You can get the same result by `S (BEG : (BEG + LEN - 1))'. - Function File: tolower (S) Return a copy of the string S, with each upper-case character replaced by the corresponding lower-case one; nonalphabetic characters are left unchanged. For example, tolower ("MiXeD cAsE 123") => "mixed case 123" - Function File: toupper (S) Returns a copy of the string S, with each lower-case character replaced by the corresponding upper-case one; nonalphabetic characters are left unchanged. For example, toupper ("MiXeD cAsE 123") => "MIXED CASE 123" - Function File: toascii (S) Return ASCII representation of S in a matrix. For example, toascii ("ASCII") => [ 65, 83, 67, 73, 73 ] Octave also provides the following C-type character class test functions. They all operate on string arrays and return matrices of zeros and ones. Elements that are nonzero indicate that the condition was true for the corresponding character in the string array. - Mapping Function: isalnum (S) letter or a digit - Mapping Function: isalpha (S) letter - Mapping Function: isascii (S) ascii - Mapping Function: iscntrl (S) control character - Mapping Function: isdigit (S) digit - Mapping Function: isgraph (S) printable (but not space character) - Mapping Function: islower (S) lower case - Mapping Function: isprint (S) printable (including space character) - Mapping Function: ispunct (S) punctuation - Mapping Function: isspace (S) whitespace - Mapping Function: isupper (S) upper case - Mapping Function: isxdigit (S) hexadecimal digit  File: octave.info, Node: System Utilities, Next: Command History Functions, Prev: String Functions, Up: Top System Utilities **************** This chapter describes the functions that are available to allow you to get information about what is happening outside of Octave, while it is still running, and use this information in your program. For example, you can get information about environment variables, the current time, and even start other programs from the Octave prompt. * Menu: * Timing Utilities:: * Filesystem Utilities:: * Interacting with the OS:: * Password Database Functions:: * Group Database Functions:: * System Information:: * Other Functions::  File: octave.info, Node: Timing Utilities, Next: Filesystem Utilities, Prev: System Utilities, Up: System Utilities Timing Utilities ================ - Loadable Function: time () Return the current time as the number of seconds since the epoch. The epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan 1970. Several of Octave's time functions a data structure for time that includes the following elements: `usec' Microseconds after the second (0-999999). `sec' Seconds after the minute (0-61). This number can be 61 to account for leap seconds. `min' Minutes after the hour (0-59). `hour' Hours since midnight (0-23). `mday' Day of the month (1-31). `mon' Months since January (0-11). `year' Years since 1900. `wday' Days since Sunday (0-6). `yday' Days since January 1 (0-365). `isdst' Daylight Savings Time flag. `zone' Time zone. - Loadable Function: mktime (TIME_STRUCT) Convert a time structure to the number of seconds since the epoch. - Loadable Function: localtime (T) Given a value returned from time (or any nonnegative integer), return a time structure corresponding to the local time zone. - Loadable Function: gmtime (T) Given a value returned from time (or any nonnegative integer), return a time structure corresponding to CUT. - Function File: asctime (TIME_STRUCT) Convert a time structure to a string using the following five-field format: Thu Mar 28 08:40:14 1996. The function `ctime (time)' is equivalent to `asctime (localtime (time))'. - Loadable Function: strftime (TIME_STRUCT) Format a time structure in a flexible way using `%' substitutions similar to those in `printf'. Except where noted, substituted fields have a fixed size; numeric fields are padded if necessary. Padding is with zeros by default; for fields that display a single number, padding can be changed or inhibited by following the `%' with one of the modifiers described below. Unknown field specifiers are copied as normal characters. All other characters are copied to the output without change. Octave's `strftime' function supports a superset of the ANSI C field specifiers. Literal character fields: `%' % character. `n' Newline character. `t' Tab character. Numeric modifiers (a nonstandard extension): `-' Do not pad the field. `_' Pad the field with spaces. Time fields: `%H' Hour (00-23). `%I' Hour (01-12). `%k' Hour (0-23). `%l' Hour (1-12). `%M' Minute (00-59). `%p' Locale's AM or PM. `%r' Time, 12-hour (hh:mm:ss [AP]M). `%R' Time, 24-hour (hh:mm). `%s' Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension). `%S' Second (00-61). `%T' Time, 24-hour (hh:mm:ss). `%X' Locale's time representation (%H:%M:%S). `%Z' Time zone (EDT), or nothing if no time zone is determinable. Date fields: `%a' Locale's abbreviated weekday name (Sun-Sat). `%A' Locale's full weekday name, variable length (Sunday-Saturday). `%b' Locale's abbreviated month name (Jan-Dec). `%B' Locale's full month name, variable length (January-December). `%c' Locale's date and time (Sat Nov 04 12:02:33 EST 1989). `%C' Century (00-99). `%d' Day of month (01-31). `%e' Day of month ( 1-31). `%D' Date (mm/dd/yy). `%h' Same as %b. `%j' Day of year (001-366). `%m' Month (01-12). `%U' Week number of year with Sunday as first day of week (00-53). `%w' Day of week (0-6). `%W' Week number of year with Monday as first day of week (00-53). `%x' Locale's date representation (mm/dd/yy). `%y' Last two digits of year (00-99). `%Y' Year (1970-). - Function File: clock () Return a vector containing the current year, month (1-12), day (1-31), hour (0-23), minute (0-59) and second (0-61). For example, octave:13> clock ans = 1993 8 20 4 56 1 The function clock is more accurate on systems that have the `gettimeofday' function. - Function File: date () Returns the date as a character string in the form DD-MMM-YY. For example, octave:13> date ans = 20-Aug-93 - Function File: tic () - Function File: toc () These functions set and check a wall-clock timer. For example, tic (); # many computations later... elapsed_time = toc (); will set the variable `elapsed_time' to the number of seconds since the most recent call to the function `tic'. - Function File: etime (T1, T2) Return the difference (in seconds) between two time values returned from `clock'. For example: t0 = clock (); # many computations later... elapsed_time = etime (clock (), t0); will set the variable `elapsed_time' to the number of seconds since the variable `t0' was set. - Built-in Function: [TOTAL, USER, SYSTEM] = cputime (); Return the CPU time used by your Octave session. The first output is the total time spent executing your process and is equal to the sum of second and third outputs, which are the number of CPU seconds spent executing in user mode and the number of CPU seconds spent executing in system mode, respectively. If your system does not have a way to report CPU time usage, `cputime' returns 0 for each of its output values. - Function File: is_leap_year (YEAR) Return 1 if the given year is a leap year and 0 otherwise. If no arguments are provided, `is_leap_year' will use the current year. For example, octave:13> is_leap_year (2000) ans = 1  File: octave.info, Node: Filesystem Utilities, Next: Interacting with the OS, Prev: Timing Utilities, Up: System Utilities Filesystem Utilities ==================== Octave includes the following functions for renaming and deleting files, creating, deleting, and reading directories, and for getting information about the status of files. - Built-in Function: rename (FROM, TO) Rename a file. - Built-in Function: unlink (FILE) Delete a file. - Built-in Function: readdir (DIR) Returns names of files in the directory DIR as an array of strings. - Built-in Function: mkdir (DIR) Create a directory - Built-in Function: rmdir (DIR) Remove a directory. - Built-in Function: umask (MASK) Set permission mask for file creation. - Built-in Function: stat (FILE) Get information about a file. If FILE is a symbolic link, `stat' returns information about the file that the symbolic link references. - Built-in Function: lstat (FILE) Get information about a symbolic link. If FILE is not a symbolic link, `lstat' is equivalent to `stat'. - Built-in Function: glob (PATTERN) Given an array of strings in PATTERN, return the list of file names that any of them, or an empty string if no patterns match. Tilde expansion is performed on each of the patterns before looking for matching file names. - Built-in Function: fnmatch (PATTERN, STRING) Return 1 or zero for each element of STRING that matches any of the elements of the string array PATTERN, using the rules of filename pattern matching.  File: octave.info, Node: Interacting with the OS, Next: Password Database Functions, Prev: Filesystem Utilities, Up: System Utilities Interacting with the OS ======================= - Built-in Function: fork () Create a copy of the current process. - Built-in Function: exec (FILE, ARGS) Replace current process with a new process. - Built-in Function: fid = dup2 (OLD, NEW) Duplicate a file descriptor. - Built-in Function: [FILE_IDS, STATUS] = pipe () Create an interprocess channel. - Built-in Function: fcntl (FID, REQUEST, ARGUMENT) Control open file descriptors. `F_DUPFD' `F_GETFD' `F_GETFL' `F_SETFD' `F_SETFL' `O_APPEND' `O_CREAT' `O_EXCL' `O_NONBLOCK' `O_RDONLY' `O_RDWR' `O_TRUNC' `O_WRONLY' - Built-in Function: getpgrp () Return the process group id of the current process. - Built-in Function: getpid () Return the process id of the current process. - Built-in Function: getppid () Return the process id of the parent process. - Built-in Function: geteuid () Return the effective user id of the current process. - Built-in Function: getuid () Return the real user id of the current process. - Built-in Function: getegid () Return the effective group id of the current process. - Built-in Function: getgid () Return the real group id of the current process. - Built-in Function: mkfifo Create a FIFO special file. - Built-in Function: waitpid Check the status of or wait for subprocesses. - Built-in Function: atexit (FCN) Register function to be called when Octave exits. - Built-in Function: system (STRING, RETURN_OUTPUT, TYPE) Execute a shell command specified by STRING. The second argument is optional. If TYPE is `"async"', the process is started in the background and the process id of the child proces is returned immediately. Otherwise, the process is started, and Octave waits until it exits. If TYPE argument is omitted, a value of `"sync"' is assumed. If two input arguments are given (the actual value of RETURN_OUTPUT is irrelevant) and the subprocess is started synchronously, or if SYSTEM is called with one input argument and one or more output arguments, the output from the command is returned. Otherwise, if the subprocess is executed synchronously, it's output is sent to the standard output. To send the output of a command executed with SYSTEM through the pager, use a command like disp (system (cmd, 1)); or printf ("%s\n", system (cmd, 1)); The `system' function can return two values. The first is any output from the command that was written to the standard output stream, and the second is the output status of the command. For example, [output, status] = system ("echo foo; exit 2"); will set the variable `output' to the string `foo', and the variable `status' to the integer `2'. - Built-in Variable: EXEC_PATH The variable `EXEC_PATH' is a colon separated list of directories to search when executing subprograms. Its initial value is taken from the environment variable `OCTAVE_EXEC_PATH' (if it exists) or `PATH', but that value can be overridden by the the command line argument `--exec-path PATH', or by setting the value of `EXEC_PATH' in a startup script. If the value of `EXEC_PATH' begins (ends) with a colon, the directories OCTAVE_HOME/libexec/octave/site/exec/ARCH OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH OCTAVE_HOME/bin are prepended (appended) to `EXEC_PATH', where `OCTAVE_HOME' is the top-level directory where all of Octave is installed (`/usr/local' by default). If you don't specify a value for `EXEC_PATH' explicitly, these special directories are prepended to your shell path. - Built-in Function: getenv (VAR) Returns the value of the environment variable VAR. For example, getenv ("PATH") returns a string containing the value of your path. - Built-in Function: putenv (VAR, VALUE) Set the value of the environment variable VAR to VALUE. - Built-in Function: clc () - Built-in Function: home () Clear the terminal screen and move the cursor to the upper left corner. - Command: cd DIR - Command: chdir DIR Change the current working directory to DIR. For example, cd ~/octave Changes the current working directory to `~/octave'. If the directory does not exist, an error message is printed and the working directory is not changed. - Built-in Function: pwd () Returns the current working directory. - Built-in Variable: PWD The current working directory. The value of `PWD' is updated each time the current working directory is changed with the `cd' command. - Command: ls - Command: dir List directory contents. For example, octave:13> ls -l total 12 -rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m -rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m The `dir' and `ls' commands are implemented by calling your system's directory listing command, so the available options may vary from system to system.  File: octave.info, Node: Password Database Functions, Next: Group Database Functions, Prev: Interacting with the OS, Up: System Utilities Password Database Functions =========================== Octave's password database functions return information in a structure with the following fields. `name' The user name. `passwd' The encrypted password, if available. `uid' The numeric user id. `gid' The numeric group id. `gecos' The GECOS field. `dir' The home directory. `shell' The initial shell. - Loadable Function: passwd_struct = getpwent () Return an entry from the password database, opening it if necessary. Once the end of the data has been reached, `getpwent' returns 0. - Loadable Function: passwd_struct = getpwuid (UID). Return the first entry from the password database with the user ID UID. If the user ID does not exist in the database, `getpwuid' returns 0. - Loadable Function: passwd_struct = getpwnam (NAME) Return the first entry from the password database with the user name NAME. If the user name does not exist in the database, `getpwname' returns 0. - Loadable Function: setpwent () Return the internal pointer to the beginning of the password database. - Loadable Function: endpwent () Close the password database.  File: octave.info, Node: Group Database Functions, Next: System Information, Prev: Password Database Functions, Up: System Utilities Group Database Functions ======================== Octave's group database functions return information in a structure with the following fields. `name' The user name. `passwd' The encrypted password, if available. `gid' The numeric group id. `mem' The members of the group. - Loadable Function: group_struct = getgrent () Return an entry from the group database, opening it if necessary. Once the end of the data has been reached, `getgrent' returns 0. - Loadable Function: group_struct = getgrgid (GID). Return the first entry from the group database with the group ID GID. If the group ID does not exist in the database, `getgrgid' returns 0. - Loadable Function: group_struct = getgrnam (NAME) Return the first entry from the group database with the group name NAME. If the group name does not exist in the database, `getgrname' returns 0. - Loadable Function: setgrent () Return the internal pointer to the beginning of the group database. - Loadable Function: endgrent () Close the group database.  File: octave.info, Node: System Information, Next: Other Functions, Prev: Group Database Functions, Up: System Utilities System Information ================== - Built-in Function: computer () Returns a string of the form CPU-VENDOR-OS that identifies the kind of computer Octave is running on. For example, octave:13> computer sparc-sun-sunos4.1.2 - Built-in Function: isieee () Return 1 if your computer claims to conform to the IEEE standard for floating point calculations. - Built-in Function: version () Returns Octave's version number as a string. This is also the value of the built-in variable `OCTAVE_VERSION'. *Note Built-in Variables::. - Loadable Function: getrusage () Return a structure containing a number of statistics about the current Octave process. Not all fields are available on all systems. If it is not possible to get CPU time statistics, the CPU time slots are set to zero. Other missing data are replaced by NaN. Here is a list of all the possible fields that can be present in the structure returned by `getrusage': `' `idrss' Unshared data size. `inblock' Number of block input operations. `isrss' Unshared stack size. `ixrss' Shared memory size. `majflt' Number of major page faults. `maxrss' Maximum data size. `minflt' Number of minor page faults. `msgrcv' Number of messages received. `msgsnd' Number of messages sent. `nivcsw' Number of involuntary context switches. `nsignals' Number of signals received. `nswap' Number of swaps. `nvcsw' Number of voluntary context switches. `oublock' Number of block output operations. `stime' A structure containing the system CPU time used. The structure has the elements `sec' (seconds) `usec' (microseconds). `utime' A structure containing the user CPU time used. The structure has the elements `sec' (seconds) `usec' (microseconds).  File: octave.info, Node: Other Functions, Prev: System Information, Up: System Utilities Other Functions =============== - Built-in Function: tilde_expand (STRING) Performs tilde expansion on STRING. - Built-in Function: pause (SECONDS) Suspend the execution of the program. If invoked without any arguments, Octave waits until you type a character. With a numeric argument, it pauses for the given number of seconds. For example, the following statement prints a message and then waits 5 seconds before clearing the screen. fprintf (stderr, "wait please...\n"); pause (5); clc;  File: octave.info, Node: Command History Functions, Next: Help, Prev: System Utilities, Up: Top Command History Functions ************************* Octave provides three functions for viewing, editing, and re-running chunks of commands from the history list. - Command: history OPTIONS If invoked with no arguments, `history' displays a list of commands that you have executed. Valid options are: `-w file' Write the current history to the named file. If the name is omitted, use the default history file (normally `~/.octave_hist'). `-r file' Read the named file, replacing the current history list with its contents. If the name is omitted, use the default history file (normally `~/.octave_hist'). `N' Only display the most recent `N' lines of history. `-q' Don't number the displayed lines of history. This is useful for cutting and pasting commands if you are using the X Window System. For example, to display the five most recent commands that you have typed without displaying line numbers, use the command `history -q 5'. - Command: edit_history OPTIONS If invoked with no arguments, `edit_history' allows you to edit the history list using the editor named by the variable `EDITOR'. The commands to be edited are first copied to a temporary file. When you exit the editor, Octave executes the commands that remain in the file. It is often more convenient to use `edit_history' to define functions rather than attempting to enter them directly on the command line. By default, the block of commands is executed as soon as you exit the editor. To avoid executing any commands, simply delete all the lines from the buffer before exiting the editor. The `edit_history' command takes two optional arguments specifying the history numbers of first and last commands to edit. For example, the command edit_history 13 extracts all the commands from the 13th through the last in the history list. The command edit_history 13 169 only extracts commands 13 through 169. Specifying a larger number for the first command than the last command reverses the list of commands before placing them in the buffer to be edited. If both arguments are omitted, the previous command in the history list is used. - Built-in Variable: EDITOR A string naming the editor to use with the `edit_history' command. If the environment variable `EDITOR' is set when Octave starts, its value is used as the default. Otherwise, `EDITOR' is set to `"vi"'. - Command: run_history Similar to `edit_history', except that the editor is not invoked, and the commands are simply executed as they appear in the history list. - Built-in Variable: history_file This variable specifies the name of the file used to store command history. The default value is `"~/.octave_hist"', but may be overridden by the environment variable `OCTAVE_HISTFILE'. - Built-in Variable: history_size This variable specifies how many entries to store in the history file. The default value is `1024', but may be overridden by the environment variable `OCTAVE_HISTSIZE'. - Built-in Variable: saving_history If the value of `saving_history' is `"true"', command entered on the command line are saved in the file specified by the variable `history_file'. - Command: diary The `diary' command allows you to create a list of all commands *and* the output they produce, mixed together just as you see them on your terminal. For example, the command diary on tells Octave to start recording your session in a file called `diary' in your current working directory. To give Octave the name of the file write to, use the a command like diary my-diary.txt Then Octave will write all of your commands to the file `my-diary.txt'. To stop recording your session, use the command diary off Without any arguments, `diary' toggles the current diary state. - Command: echo OPTIONS Control whether commands are displayed as they are executed. Valid options are: `on' Enable echoing of commands as they are executed in script files. `off' Disable echoing of commands as they are executed in script files. `on all' Enable echoing of commands as they are executed in script files and functions. `off all' Disable echoing of commands as they are executed in script files and functions. If invoked without any arguments, `echo' toggles the current echo state. - Built-in Variable: echo_executing_commands  File: octave.info, Node: Help, Next: Programming Utilities, Prev: Command History Functions, Up: Top Help **** - Command: help Octave's `help' command can be used to print brief usage-style messages, or to display information directly from an on-line version of the printed manual, using the GNU Info browser. If invoked without any arguments, `help' prints a list of all the available operators, functions, and built-in variables. If the first argument is `-i', the `help' command searches the index of the on-line version of this manual for the given topics. For example, the command help help prints a short message describing the `help' command, and help -i help starts the GNU Info browser at this node in the on-line version of the manual. *Note Using Info::, for complete details about how to use the GNU Info browser to read the on-line version of the manual. The help command can give you information about operators, but not the comma and semicolons that are used as command separators. To get help for those, you must type `help comma' or `help semicolon'. - Built-in Variable: INFO_FILE The variable `INFO_FILE' names the location of the Octave info file. The default value is `"/ade/info/octave.info"'. - Built-in Variable: INFO_PROGRAM The variable `INFO_PROGRAM' names the info program to run. Its initial value is `/ade/libexec/octave/VERSION/exec/ARCH/info', but that value can be overridden by the environment variable `OCTAVE_INFO_PROGRAM', or the command line argument `--info-program NAME', or by setting the value of `INFO_PROGRAM' in a startup script. - Built-in Variable: suppress_verbose_help_message If the value of `suppress_verbose_help_message' is nonzero, Octave will not add additional help information to the end of the output from the `help' command and usage messages for built-in commands.  File: octave.info, Node: Programming Utilities, Next: Amusements, Prev: Help, Up: Top Programming Utilities ********************* * Menu: * Evaluating Strings as Commands:: * Miscellaneous Utilities::  File: octave.info, Node: Evaluating Strings as Commands, Next: Miscellaneous Utilities, Prev: Programming Utilities, Up: Programming Utilities Evaluating Strings as Commands ============================== It is often useful to evaluate a string as if it were an Octave program, or use a string as the name of a function to call. These functions are necessary in order to evaluate commands that are not known until run time, or to write functions that will need to call user-supplied functions. - Built-in Function: eval (COMMAND) Parse the string COMMAND and evaluate it as if it were an Octave program, returning the last value computed. The COMMAND is evaluated in the current context, so any results remain available after `eval' returns. For example, octave:13> a error: `a' undefined octave:14> eval ("a = 13") a = 13 ans = 13 octave:15> a a = 13 In this case, two values are printed: one for the expression that was evaluated, and one for the value returned from `eval'. Just as with any other expression, you can turn printing off by ending the expression in a semicolon. For example, octave:13> a error: `a' undefined octave:14> eval ("a = 13;") ans = 13 octave:15> a a = 13 - Built-in Function: feval (NAME, ...) Evaluate the function named NAME. Any arguments after the first are passed on to the named function. For example, octave:12> feval ("acos", -1) ans = 3.1416 calls the function `acos' with the argument `-1'. The function `feval' is necessary in order to be able to write functions that call user-supplied functions, because Octave does not have a way to declare a pointer to a function (like C) or to declare a special kind of variable that can be used to hold the name of a function (like `EXTERNAL' in Fortran). Instead, you must refer to functions by name, and use `feval' to call them. Here is a simple-minded function using `feval' that finds the root of a user-supplied function of one variable. function result = newtroot (fname, x) # usage: newtroot (fname, x) # # fname : a string naming a function f(x). # x : initial guess delta = tol = sqrt (eps); maxit = 200; fx = feval (fname, x); for i = 1:maxit if (abs (fx) < tol) result = x; return; else fx_new = feval (fname, x + delta); deriv = (fx_new - fx) / delta; x = x - fx / deriv; fx = fx_new; endif endfor result = x; endfunction Note that this is only meant to be an example of calling user-supplied functions and should not be taken too seriously. In addition to using a more robust algorithm, any serious code would check the number and type of all the arguments, ensure that the supplied function really was a function, etc.