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.
Octave's core set of functions for manipulating time values are patterned after the corresponding functions from the standard C library. Several of these functions use a data structure for time that includes the following elements:
usec
sec
min
hour
mday
mon
year
wday
yday
isdst
zone
In the descriptions of the following functions, this structure is referred to as a tm_struct.
time was 856163706.
time (or any other nonnegative
integer), to the local time and return a string of the same form as
asctime. The function ctime (time) is equivalent to
asctime (localtime (time)). For example,
ctime (time ())
=> "Mon Feb 17 01:15:06 1997"
gmtime (time ())
=> {
usec = 0
year = 97
mon = 1
mday = 17
sec = 6
zone = CST
min = 15
wday = 1
hour = 7
isdst = 0
yday = 47
}
localtime (time ())
=> {
usec = 0
year = 97
mon = 1
mday = 17
sec = 6
zone = CST
min = 15
wday = 1
hour = 1
isdst = 0
yday = 47
}
mktime (localtime (time ())
=> 856163706
asctime (localtime (time ())
=> "Mon Feb 17 01:15:06 1997\n"
This is equivalent to ctime (time ()).
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. For example,
strftime ("%r (%Z) %A %e %B %Y", localtime (time ())
=> "01:15:06 AM (CST) Monday 17 February 1997"
Octave's strftime function supports a superset of the ANSI C
field specifiers.
Literal character fields:
%
n
t
Numeric modifiers (a nonstandard extension):
- (dash)
_ (underscore)
Time fields:
%H
%I
%k
%l
%M
%p
%r
%R
%s
%S
%T
%X
%Z
Date fields:
%a
%A
%b
%B
%c
%C
%d
%e
%D
%h
%j
%m
%U
%w
%W
%x
%y
%Y
Most of the remaining functions described in this section are not patterned after the standard C library. Some are available for compatiblity with MATLAB and others are provided because they are useful.
clock ()
=> [ 1993, 8, 20, 4, 56, 1 ]
The function clock is more accurate on systems that have the
gettimeofday function.
date ()
=> "20-Aug-93"
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.
cputime returns 0 for each of its output values.
Note that because Octave used some CPU time to start, it is reasonable
to check to see if cputime works by checking to see if the total
CPU time used is nonzero.
is_leap_year will use the current year.
For example,
is_leap_year (2000)
=> 1
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.
If you are more interested in the CPU time that your process used, you
should use the cputime function instead. The tic and
toc functions report the actual wall clock time that elapsed
between the calls. This may include time spent processing other jobs or
doing nothing at all. For example,
tic (); sleep (5); toc ()
=> 5
t = cputime (); sleep (5); cputime () - t
=> 0
(This example also illustrates that the CPU timer may have a fairly coarse resolution.)
fprintf (stderr, "wait please...\n"); pause (5); clc;
usleep will pause the execution for
round (microseconds / 1e6) seconds.
Octave includes the following functions for renaming and deleting files, creating, deleting, and reading directories, and for getting information about the status of files.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
dev
ino
modestr
nlink
uid
gid
rdev
size
atime
time. See section Timing Utilities.
mtime
time. See section Timing Utilities.
ctime
time. See section Timing Utilities.
blksize
blocks
If the call is successful err is 0 and msg is an empty string. If the file does not exist, or some other error occurs, s is an empty matrix, err is -1, and msg contains the corresponding system error message.
If file is a symbolic link, stat will return information
about the actual file the is referenced by the link. Use lstat
if you want information about the symbolic link itself.
For example,
[s, err, msg] = stat ("/vmlinuz")
=> s =
{
atime = 855399756
rdev = 0
ctime = 847219094
uid = 0
size = 389218
blksize = 4096
mtime = 847219094
gid = 6
nlink = 1
blocks = 768
modestr = -rw-r--r--
ino = 9316
dev = 2049
}
=> err = 0
=> msg =
glob ("/vm*")
=> "/vmlinuz"
Note that multiple values are returned in a string matrix with the fill character set to ASCII NUL.
fnmatch ("a*b", ["ab"; "axyzb"; "xyzab"])
=> [ 1; 1; 0 ]
LOADPATH.
If the file cannot be found in the path, an empty matrix is returned. For example,
file_in_path (LOADPATH, "nargchk.m")
=> "/usr/local/share/octave/2.0/m/general/nargchk.m"
tilde_expand ("~joeuser/bin")
=> "/home/joeuser/bin"
tilde_expand ("~/bin")
=> "/home/jwe/bin"
Octave includes some high-level commands like system and
popen for starting subprocesses. If you want to run another
program to perform some task and then look at its output, you will
probably want to use these functions.
Octave also provides several very low-level Unix-like functions which can also be used for starting subprocesses, but you should probably only use them if you can't find any way to do what you need with the higher-level functions.
"async", the process is started in the
background and the process id of the child process 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'.
"r"
"w"
For example,
fid = popen ("ls -ltr / | tail -3", "r");
while (isstr (s = fgets (fid)))
fputs (stdout, s);
endwhile
-| drwxr-xr-x 33 root root 3072 Feb 15 13:28 etc
-| drwxr-xr-x 3 root root 1024 Feb 15 13:28 lib
-| drwxrwxrwt 15 root root 2048 Feb 17 14:53 tmp
popen. You may also
use fclose for the same purpose.
For example,
[in, out, pid] = popen2 ("sort", "-nr");
fputs (in, "these\nare\nsome\nstrings\n");
fclose (in);
while (isstr (s = fgets (out)))
fputs (stdout, s);
endwhile
fclose (out);
-| are
-| some
-| strings
-| these
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 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
are prepended (appended) to EXEC_PATH, where octave-home
is the top-level directory where all of Octave is installed
(the default value is `/usr/local'). If you don't specify
a value for EXEC_PATH explicitly, these special directories are
prepended to your shell path.
In most cases, the following functions simply decode their arguments and
make the corresponding Unix system calls. For a complete example of how
they can be used, look at the definition of the function popen2.
Fork can return one of the following values:
fork is
the process id of the child process. You should probably arrange to
wait for any child processes to exit.
exec to start another
process. If that fails, you should probably call exit.
fork failed for some reason. You must take evasive
action. A system dependent error message will be waiting in msg.
exec without
first calling fork will terminate your current Octave process and
replace it with the program named by file. For example,
exec ("ls" "-l")
will run ls and return you to your shell prompt.
If successful, exec does not return. If exec does return,
err will be nonzero, and msg will contain a system-dependent
error message.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
If successful, fid is greater than zero and contains the new file ID. Otherwise, fid is negative and msg contains a system-dependent error message.
The options argument can be:
If the returned value of pid is greater than 0, it is the process ID of the child process that exited. If an error occurs, pid will be less than zero and msg will contain a system-dependent error message.
F_DUPFD
F_GETFD
F_SETFD
F_GETFL
O_RDONLY
O_WRONLY
O_RDWR
O_APPEND
O_NONBLOCK
O_SYNC
O_ASYNC
F_SETFL
O_APPEND and
O_NONBLOCK.
If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.
getenv ("PATH")
returns a string containing the value of your path.
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.
PWD is updated each
time the current working directory is changed with the `cd'
command.
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.
Octave's password database functions return information in a structure with the following fields.
name
passwd
uid
gid
gecos
dir
shell
In the descriptions of the following functions, this data structure is referred to as a pw_struct.
getpwent returns 0.
getpwuid returns 0.
getpwname returns 0.
Octave's group database functions return information in a structure with the following fields.
name
passwd
gid
mem
In the descriptions of the following functions, this data structure is referred to as a grp_struct.
getgrent returns 0.
getgrgid returns 0.
getgrname returns 0.
computer ()
-| i586-pc-linux-gnu
x = computer ()
=> x = "i586-pc-linux-gnu"
OCTAVE_VERSION.
getrusage:
idrss
inblock
isrss
ixrss
majflt
maxrss
minflt
msgrcv
msgsnd
nivcsw
nsignals
nswap
nvcsw
oublock
stime
sec (seconds) usec (microseconds).
utime
sec (seconds) usec (microseconds).
Go to the first, previous, next, last section, table of contents.