Mercurial > hg > octave-lyh
changeset 3301:02866242d3ae
[project @ 1999-10-20 04:10:46 by jwe]
author | jwe |
---|---|
date | Wed, 20 Oct 1999 04:10:53 +0000 |
parents | cfbe664b5ebf |
children | bac635def477 |
files | doc/ChangeLog doc/interpreter/munge-texi.cc doc/interpreter/system.txi examples/make_int.cc scripts/ChangeLog scripts/miscellaneous/cputime.m scripts/miscellaneous/etime.m scripts/miscellaneous/is_leap_year.m scripts/miscellaneous/popen2.m scripts/miscellaneous/tic.m scripts/miscellaneous/toc.m scripts/miscellaneous/version.m scripts/time/asctime.m scripts/time/clock.m scripts/time/date.m src/ChangeLog src/DLD-FUNCTIONS/getgrent.cc src/DLD-FUNCTIONS/getpwent.cc src/DLD-FUNCTIONS/getrusage.cc src/DLD-FUNCTIONS/time.cc src/Makefile.in src/defaults.cc src/dirfns.cc src/file-io.cc src/help.cc src/ov.h src/syscalls.cc src/sysdep.cc src/toplev.cc src/utils.cc |
diffstat | 30 files changed, 1104 insertions(+), 1277 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,5 +1,8 @@ 1999-10-19 John W. Eaton <jwe@bevo.che.wisc.edu> + * interpreter/munge-texi.cc: Strip the "-*- texinfo -*-" marker + when including help text. + * interpreter/Makefile.in ($(TEXINFO)): Depend on $(DOCSTRINGS). ($(DOCSTRINGS)): New rule.
--- a/doc/interpreter/munge-texi.cc +++ b/doc/interpreter/munge-texi.cc @@ -1,6 +1,7 @@ #include <iostream.h> #include <fstream.h> #include <string> +#include <cctype> #include <map> static const char doc_delim = ''; @@ -114,7 +115,25 @@ if (is.eof ()) fatal ("end of file while reading @DOCSTRING command"); else - os << help_text[symbol_name]; + { + string doc_string = help_text[symbol_name]; + + int i = 0; + while (doc_string[i] == ' ') + i++; + + if (doc_string.substr (i, 15) == "-*- texinfo -*-") + { + i += 15; + + while (isspace (doc_string[i])) + i++; + + os << doc_string.substr (i); + } + else + os << doc_string; + } } else {
--- a/doc/interpreter/system.txi +++ b/doc/interpreter/system.txi @@ -71,88 +71,17 @@ In the descriptions of the following functions, this structure is referred to as a @var{tm_struct}. -@deftypefn {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. For example, on Monday February 17, 1997 at 07:15:06 CUT, the -value returned by @code{time} was 856163706. -@end deftypefn +@DOCSTRING(time) @DOCSTRING(ctime) -@deftypefn {Loadable Function} {} gmtime (@var{t}) -Given a value returned from time (or any nonnegative integer), -return a time structure corresponding to CUT. For example, +@DOCSTRING(gmtime) -@example -@group -gmtime (time ()) - @result{} @{ - usec = 0 - year = 97 - mon = 1 - mday = 17 - sec = 6 - zone = CST - min = 15 - wday = 1 - hour = 7 - isdst = 0 - yday = 47 - @} -@end group -@end example -@end deftypefn - -@deftypefn {Loadable Function} {} localtime (@var{t}) -Given a value returned from time (or any nonnegative integer), -return a time structure corresponding to the local time zone. +@DOCSTRING(localtime) -@example -@group -localtime (time ()) - @result{} @{ - usec = 0 - year = 97 - mon = 1 - mday = 17 - sec = 6 - zone = CST - min = 15 - wday = 1 - hour = 1 - isdst = 0 - yday = 47 - @} -@end group -@end example -@end deftypefn +@DOCSTRING(mktime) -@deftypefn {Loadable Function} {} mktime (@var{tm_struct}) -Convert a time structure corresponding to the local time to the number -of seconds since the epoch. For example, - -@example -@group -mktime (localtime (time ()) - @result{} 856163706 -@end group -@end example -@end deftypefn - -@deftypefn {Function File} {} asctime (@var{tm_struct}) -Convert a time structure to a string using the following five-field -format: Thu Mar 28 08:40:14 1996. For example, - -@example -@group -asctime (localtime (time ()) - @result{} "Mon Feb 17 01:15:06 1997\n" -@end group -@end example - -This is equivalent to @code{ctime (time ())}. -@end deftypefn +@DOCSTRING(asctime) @DOCSTRING(strftime) @@ -161,133 +90,23 @@ compatiblity with @sc{Matlab} and others are provided because they are useful. -@deftypefn {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, - -@example -@group -clock () - @result{} [ 1993, 8, 20, 4, 56, 1 ] -@end group -@end example +@DOCSTRING(clock) -The function clock is more accurate on systems that have the -@code{gettimeofday} function. -@end deftypefn - -@deftypefn {Function File} {} date () -Return the date as a character string in the form DD-MMM-YY. For -example, - -@example -@group -date () - @result{} "20-Aug-93" -@end group -@end example -@end deftypefn +@DOCSTRING(date) -@deftypefn {Function File} {} etime (@var{t1}, @var{t2}) -Return the difference (in seconds) between two time values returned from -@code{clock}. For example: - -@example -t0 = clock (); -# many computations later... -elapsed_time = etime (clock (), t0); -@end example - -@noindent -will set the variable @code{elapsed_time} to the number of seconds since -the variable @code{t0} was set. -@end deftypefn +@DOCSTRING(etime) -@deftypefn {Built-in Function} {[@var{total}, @var{user}, @var{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, @code{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 @code{cputime} works by checking to see if the total -CPU time used is nonzero. -@end deftypefn - -@deftypefn {Function File} {} is_leap_year (@var{year}) -Return 1 if the given year is a leap year and 0 otherwise. If no -arguments are provided, @code{is_leap_year} will use the current year. -For example, +@DOCSTRING(cputime) -@example -@group -is_leap_year (2000) - @result{} 1 -@end group -@end example -@end deftypefn - -@deftypefn {Function File} {} tic () -@deftypefnx {Function File} {} toc () -These functions set and check a wall-clock timer. For example, +@DOCSTRING(is_leap_year) -@example -tic (); -# many computations later... -elapsed_time = toc (); -@end example - -@noindent -will set the variable @code{elapsed_time} to the number of seconds since -the most recent call to the function @code{tic}. - -If you are more interested in the CPU time that your process used, you -should use the @code{cputime} function instead. The @code{tic} and -@code{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, +@DOCSTRING(tic) -@example -@group -tic (); sleep (5); toc () - @result{} 5 -t = cputime (); sleep (5); cputime () - t - @result{} 0 -@end group -@end example - -@noindent -(This example also illustrates that the CPU timer may have a fairly -coarse resolution.) -@end deftypefn +@DOCSTRING(pause) -@deftypefn {Built-in Function} {} pause (@var{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. +@DOCSTRING(sleep) -@example -@group -fprintf (stderr, "wait please...\n"); -pause (5); -clc; -@end group -@end example -@end deftypefn - -@deftypefn {Built-in Function} {} sleep (@var{seconds}) -Suspend the execution of the program for the given number of seconds. -@end deftypefn - -@deftypefn {Built-in Function} {} usleep (@var{microseconds}) -Suspend the execution of the program for the given number of -microseconds. On systems where it is not possible to sleep for periods -of time less than one second, @code{usleep} will pause the execution for -@code{round (@var{microseconds} / 1e6)} seconds. -@end deftypefn +@DOCSTRING(usleep) @node Filesystem Utilities, Controlling Subprocesses, Timing Utilities, System Utilities @section Filesystem Utilities @@ -296,212 +115,27 @@ creating, deleting, and reading directories, and for getting information about the status of files. -@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new}) -Change the name of file @var{old} to @var{new}. - -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} unlink (@var{file}) -Delete @var{file}. - -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir}) -Return names of the files in the directory @var{dir} as an array of -strings. If an error occurs, return an empty matrix in @var{files}. +@DOCSTRING(rename) -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkdir (@var{dir}) -Create a directory named @var{dir}. - -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rmdir (@var{dir}) -Remove the directory named @var{dir}. - -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkfifo (@var{name}) -Create a FIFO special file. - -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn +@DOCSTRING(unlink) -@c XXX FIXME XXX -- this needs to be explained, but I don't feel up to -@c it just now... - -@deftypefn {Built-in Function} {} umask (@var{mask}) -Set the permission mask for file creation. The parameter @var{mask} is -interpreted as an octal number. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file}) -@deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file}) -Return a structure @var{s} containing the following information about -@var{file}. - -@table @code -@item dev -ID of device containing a directory entry for this file. - -@item ino -File number of the file. - -@item modestr -File mode, as a string of ten letters or dashes as would be returned by -@kbd{ls -l}. - -@item nlink -Number of links. +@DOCSTRING(readdir) -@item uid -User ID of file's owner. - -@item gid -Group ID of file's group. - -@item rdev -ID of device for block or character special files. - -@item size -Size in bytes. +@DOCSTRING(mkdir) -@item atime -Time of last access in the same form as time values returned from -@code{time}. @xref{Timing Utilities}. - -@item mtime -Time of last modification in the same form as time values returned from -@code{time}. @xref{Timing Utilities}. - -@item ctime -Time of last file status change in the same form as time values returned from -@code{time}. @xref{Timing Utilities}. - -@item blksize -Size of blocks in the file. +@DOCSTRING(rmdir) -@item blocks -Number of blocks allocated for file. -@end table - -If the call is successful @var{err} is 0 and @var{msg} is an empty -string. If the file does not exist, or some other error occurs, @var{s} -is an empty matrix, @var{err} is @minus{}1, and @var{msg} contains the -corresponding system error message. - -If @var{file} is a symbolic link, @code{stat} will return information -about the actual file the is referenced by the link. Use @code{lstat} -if you want information about the symbolic link itself. - -For example, +@DOCSTRING(mkfifo) -@example -@group -[s, err, msg] = stat ("/vmlinuz") - @result{} 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 - @} - @result{} err = 0 - @result{} msg = -@end group -@end example -@end deftypefn +@DOCSTRING(umask) -@deftypefn {Built-in Function} {} glob (@var{pattern}) -Given an array of strings in @var{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. For example, +@DOCSTRING(stat) -@example -@group -glob ("/vm*") - @result{} "/vmlinuz" -@end group -@end example - -Note that multiple values are returned in a string matrix with the fill -character set to ASCII NUL. -@end deftypefn - -@deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string}) -Return 1 or zero for each element of @var{string} that matches any of -the elements of the string array @var{pattern}, using the rules of -filename pattern matching. For example, - -@example -@group -fnmatch ("a*b", ["ab"; "axyzb"; "xyzab"]) - @result{} [ 1; 1; 0 ] -@end group -@end example -@end deftypefn +@DOCSTRING(glob) -@deftypefn {Built-in Function} {} file_in_path (@var{path}, @var{file}) -Return the absolute name name of @var{file} if it can be found in -@var{path}. The value of @var{path} should be a colon-separated list of -directories in the format described for the built-in variable -@code{LOADPATH}. - -If the file cannot be found in the path, an empty matrix is returned. -For example, - -@example -file_in_path (LOADPATH, "nargchk.m") - @result{} "@value{OCTAVEHOME}/share/octave/2.0/m/general/nargchk.m" -@end example -@end deftypefn +@DOCSTRING(file_in_path) -@deftypefn {Built-in Function} {} tilde_expand (@var{string}) -Performs tilde expansion on @var{string}. If @var{string} begins with a -tilde character, (@samp{~}), all of the characters preceding the first -slash (or all characters, if there is no slash) are treated as a -possible user name, and the tilde and the following characters up to the -slash are replaced by the home directory of the named user. If the -tilde is followed immediately by a slash, the tilde is replaced by the -home directory of the user running Octave. For example, - -@example -@group -tilde_expand ("~joeuser/bin") - @result{} "/home/joeuser/bin" -tilde_expand ("~/bin") - @result{} "/home/jwe/bin" -@end group -@end example -@end deftypefn +@DOCSTRING(tilde_expand) @node Controlling Subprocesses, Process ID Information, Filesystem Utilities, System Utilities @section Controlling Subprocesses @@ -516,369 +150,64 @@ use them if you can't find any way to do what you need with the higher-level functions. -@deftypefn {Built-in Function} {} system (@var{string}, @var{return_output}, @var{type}) -Execute a shell command specified by @var{string}. The second argument is optional. -If @var{type} is @code{"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 @var{type} argument is omitted, a value of @code{"sync"} -is assumed. - -If two input arguments are given (the actual value of -@var{return_output} is irrelevant) and the subprocess is started -synchronously, or if @var{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 @var{system} through the pager, use a command like - -@example -disp (system (cmd, 1)); -@end example - -@noindent -or - -@example -printf ("%s\n", system (cmd, 1)); -@end example +@DOCSTRING(system) -The @code{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, - -@example -[output, status] = system ("echo foo; exit 2"); -@end example - -@noindent -will set the variable @code{output} to the string @samp{foo}, and the -variable @code{status} to the integer @samp{2}. -@end deftypefn - -@deftypefn {Built-in Function} {fid =} popen (@var{command}, @var{mode}) -Start a process and create a pipe. The name of the command to run is -given by @var{command}. The file identifier corresponding to the input -or output stream of the process is returned in @var{fid}. The argument -@var{mode} may be - -@table @code -@item "r" -The pipe will be connected to the standard output of the process, and -open for reading. - -@item "w" -The pipe will be connected to the standard input of the process, and -open for writing. -@end table - -For example, +@DOCSTRING(popen) -@example -@group -fid = popen ("ls -ltr / | tail -3", "r"); -while (isstr (s = fgets (fid))) - fputs (stdout, s); -endwhile - @print{} drwxr-xr-x 33 root root 3072 Feb 15 13:28 etc - @print{} drwxr-xr-x 3 root root 1024 Feb 15 13:28 lib - @print{} drwxrwxrwt 15 root root 2048 Feb 17 14:53 tmp -@end group -@end example -@end deftypefn - -@deftypefn {Built-in Function} {} pclose (@var{fid}) -Close a file identifier that was opened by @code{popen}. You may also -use @code{fclose} for the same purpose. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) -Start a subprocess with two-way communication. The name of the process -is given by @var{command}, and @var{args} is an array of strings -containing options for the command. The file identifiers for the input -and output streams of the subprocess are returned in @var{in} and -@var{out}. If execution of the command is successful, @var{pid} -contains the process ID of the subprocess. Otherwise, @var{pid} is -@minus{}1. - -For example, +@DOCSTRING(pclose) -@example -@group -[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); - @print{} are - @print{} some - @print{} strings - @print{} these -@end group -@end example -@end deftypefn +@DOCSTRING(popen2) -@defvr {Built-in Variable} EXEC_PATH -The variable @code{EXEC_PATH} is a colon separated list of directories -to search when executing subprograms. Its initial value is taken from -the environment variable @code{OCTAVE_EXEC_PATH} (if it exists) or -@code{PATH}, but that value can be overridden by the command line -argument @code{--exec-path PATH}, or by setting the value of -@code{EXEC_PATH} in a startup script. If the value of @code{EXEC_PATH} -begins (ends) with a colon, the directories - -@example -@group -@var{octave-home}/libexec/octave/site/exec/@var{arch} -@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch} -@end group -@end example - -@noindent -are prepended (appended) to @code{EXEC_PATH}, where @var{octave-home} -is the top-level directory where all of Octave is installed -(the default value is @file{@value{OCTAVEHOME}}). If you don't specify -a value for @code{EXEC_PATH} explicitly, these special directories are -prepended to your shell path. -@end defvr +@DOCSTRING(EXEC_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 @code{popen2}. -@deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} fork () -Create a copy of the current process. - -Fork can return one of the following values: - -@table @asis -@item > 0 -You are in the parent process. The value returned from @code{fork} is -the process id of the child process. You should probably arrange to -wait for any child processes to exit. - -@item 0 -You are in the child process. You can call @code{exec} to start another -process. If that fails, you should probably call @code{exit}. - -@item < 0 -The call to @code{fork} failed for some reason. You must take evasive -action. A system dependent error message will be waiting in @var{msg}. -@end table -@end deftypefn - -@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args}) -Replace current process with a new process. Calling @code{exec} without -first calling @code{fork} will terminate your current Octave process and -replace it with the program named by @var{file}. For example, - -@example -exec ("ls" "-l") -@end example - -@noindent -will run @code{ls} and return you to your shell prompt. +@DOCSTRING(fork) -If successful, @code{exec} does not return. If @code{exec} does return, -@var{err} will be nonzero, and @var{msg} will contain a system-dependent -error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{file_ids}, @var{err}, @var{msg}] =} pipe () -Create a pipe and return the vector @var{file_ids}, which corresponding -to the reading and writing ends of the pipe. - -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{fid}, @var{msg}] =} dup2 (@var{old}, @var{new}) -Duplicate a file descriptor. +@DOCSTRING(exec) -If successful, @var{fid} is greater than zero and contains the new file -ID. Otherwise, @var{fid} is negative and @var{msg} contains a -system-dependent error message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} waitpid (@var{pid}, @var{options}) -Wait for process @var{pid} to terminate. The @var{pid} argument can be: - -@table @asis -@item @minus{}1 -Wait for any child process. - -@item 0 -Wait for any child process whose process group ID is equal to that of -the Octave interpreter process. - -@item > 0 -Wait for termination of the child process with ID @var{pid}. -@end table - -The @var{options} argument can be: +@DOCSTRING(pipe) -@table @asis -@item 0 -Wait until signal is received or a child process exits (this is the -default if the @var{options} argument is missing). - -@item 1 -Do not hang if status is not immediately available. - -@item 2 -Report the status of any child processes that are stopped, and whose -status has not yet been reported since they stopped. - -@item 3 -Implies both 1 and 2. -@end table - -If the returned value of @var{pid} is greater than 0, it is the process -ID of the child process that exited. If an error occurs, @var{pid} will -be less than zero and @var{msg} will contain a system-dependent error -message. -@end deftypefn - -@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg}) -Change the properties of the open file @var{fid}. The following values -may be passed as @var{request}: - -@vtable @code -@item F_DUPFD -Return a duplicate file descriptor. - -@item F_GETFD -Return the file descriptor flags for @var{fid}. - -@item F_SETFD -Set the file descriptor flags for @var{fid}. +@DOCSTRING(dup2) -@item F_GETFL -Return the file status flags for @var{fid}. The following codes may be -returned (some of the flags may be undefined on some systems). - -@vtable @code -@item O_RDONLY -Open for reading only. - -@item O_WRONLY -Open for writing only. - -@item O_RDWR -Open for reading and writing. - -@item O_APPEND -Append on each write. +@DOCSTRING(waitpid) -@item O_NONBLOCK -Nonblocking mode. - -@item O_SYNC -Wait for writes to complete. - -@item O_ASYNC -Asynchronous I/O. -@end vtable - -@item F_SETFL -Set the file status flags for @var{fid} to the value specified by -@var{arg}. The only flags that can be changed are @code{O_APPEND} and -@code{O_NONBLOCK}. -@end vtable - -If successful, @var{err} is 0 and @var{msg} is an empty string. -Otherwise, @var{err} is nonzero and @var{msg} contains a -system-dependent error message. -@end deftypefn +@DOCSTRING(fcntl) @node Process ID Information, Environment Variables, Controlling Subprocesses, System Utilities @section Process, Group, and User IDs -@deftypefn {Built-in Function} {} getpgrp () -Return the process group id of the current process. -@end deftypefn +@DOCSTRING(getpgrp) -@deftypefn {Built-in Function} {} getpid () -Return the process id of the current process. -@end deftypefn +@DOCSTRING(getpid) -@deftypefn {Built-in Function} {} getppid () -Return the process id of the parent process. -@end deftypefn +@DOCSTRING(getppid) -@deftypefn {Built-in Function} {} geteuid () -Return the effective user id of the current process. -@end deftypefn +@DOCSTRING(geteuid) -@deftypefn {Built-in Function} {} getuid () -Return the real user id of the current process. -@end deftypefn +@DOCSTRING(getuid) -@deftypefn {Built-in Function} {} getegid () -Return the effective group id of the current process. -@end deftypefn +@DOCSTRING(getegid) -@deftypefn {Built-in Function} {} getgid () -Return the real group id of the current process. -@end deftypefn +@DOCSTRING(getgid) @node Environment Variables, Current Working Directory, Process ID Information, System Utilities @section Environment Variables -@deftypefn {Built-in Function} {} getenv (@var{var}) -Return the value of the environment variable @var{var}. For example, - -@example -getenv ("PATH") -@end example +@DOCSTRING(getenv) -@noindent -returns a string containing the value of your path. -@end deftypefn - -@deftypefn {Built-in Function} {} putenv (@var{var}, @var{value}) -Set the value of the environment variable @var{var} to @var{value}. -@end deftypefn +@DOCSTRING(putenv) @node Current Working Directory, Password Database Functions, Environment Variables, System Utilities @section Current Working Directory -@deffn {Command} cd dir -@deffnx {Command} chdir dir -Change the current working directory to @var{dir}. For example, - -@example -cd ~/octave -@end example - -@noindent -Changes the current working directory to @file{~/octave}. If the -directory does not exist, an error message is printed and the working -directory is not changed. -@end deffn +@DOCSTRING(cd) -@deftypefn {Built-in Function} {} pwd () -Return the current working directory. -@end deftypefn - -@deffn {Command} ls options -@deffnx {Command} dir options -List directory contents. For example, +@DOCSTRING(ls) -@example -ls -l - @print{} total 12 - @print{} -rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m - @print{} -rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m -@end example - -The @code{dir} and @code{ls} commands are implemented by calling your -system's directory listing command, so the available options may vary -from system to system. -@end deffn +@DOCSTRING(pwd) @node Password Database Functions, Group Database Functions, Current Working Directory, System Utilities @section Password Database Functions @@ -912,31 +241,15 @@ In the descriptions of the following functions, this data structure is referred to as a @var{pw_struct}. -@deftypefn {Loadable Function} {@var{pw_struct} = } getpwent () -Return a structure containing an entry from the password database, -opening it if necessary. Once the end of the data has been reached, -@code{getpwent} returns 0. -@end deftypefn +@DOCSTRING(getpwent) -@deftypefn {Loadable Function} {@var{pw_struct} = } getpwuid (@var{uid}). -Return a structure containing the first entry from the password database -with the user ID @var{uid}. If the user ID does not exist in the -database, @code{getpwuid} returns 0. -@end deftypefn +@DOCSTRING(getpwuid) -@deftypefn {Loadable Function} {@var{pw_struct} = } getpwnam (@var{name}) -Return a structure containing the first entry from the password database -with the user name @var{name}. If the user name does not exist in the -database, @code{getpwname} returns 0. -@end deftypefn +@DOCSTRING(getpwnam) -@deftypefn {Loadable Function} {} setpwent () -Return the internal pointer to the beginning of the password database. -@end deftypefn +@DOCSTRING(setpwent) -@deftypefn {Loadable Function} {} endpwent () -Close the password database. -@end deftypefn +@DOCSTRING(endpwent) @node Group Database Functions, System Information, Password Database Functions, System Utilities @section Group Database Functions @@ -961,128 +274,25 @@ In the descriptions of the following functions, this data structure is referred to as a @var{grp_struct}. -@deftypefn {Loadable Function} {@var{grp_struct} =} getgrent () -Return an entry from the group database, opening it if necessary. -Once the end of the data has been reached, @code{getgrent} returns 0. -@end deftypefn - -@deftypefn {Loadable Function} {@var{grp_struct} =} getgrgid (@var{gid}). -Return the first entry from the group database with the group ID -@var{gid}. If the group ID does not exist in the database, -@code{getgrgid} returns 0. -@end deftypefn +@DOCSTRING(getgrent) -@deftypefn {Loadable Function} {@var{grp_struct} =} getgrnam (@var{name}) -Return the first entry from the group database with the group name -@var{name}. If the group name does not exist in the database, -@code{getgrname} returns 0. -@end deftypefn +@DOCSTRING(getgrgid) + +@DOCSTRING(getgrnam) -@deftypefn {Loadable Function} {} setgrent () -Return the internal pointer to the beginning of the group database. -@end deftypefn +@DOCSTRING(setgrent) -@deftypefn {Loadable Function} {} endgrent () -Close the group database. -@end deftypefn +@DOCSTRING(endgrent) @node System Information, , Group Database Functions, System Utilities @section System Information -@deftypefn {Built-in Function} {} computer () -Print or return a string of the form @var{cpu}-@var{vendor}-@var{os} -that identifies the kind of computer Octave is running on. If invoked -with an output argument, the value is returned instead of printed. For -example, - -@example -@group -computer () - @print{} i586-pc-linux-gnu - -x = computer () - @result{} x = "i586-pc-linux-gnu" -@end group -@end example -@end deftypefn - -@deftypefn {Built-in Function} {} isieee () -Return 1 if your computer claims to conform to the IEEE standard for -floating point calculations. -@end deftypefn +@DOCSTRING(computer) -@deftypefn {Built-in Function} {} version () -Return Octave's version number as a string. This is also the value of -the built-in variable @code{OCTAVE_VERSION}. -@end deftypefn - -@defvr {Built-in Variable} OCTAVE_VERSION -The version number of Octave, as a string. -@end defvr - -@deftypefn {Built-in Function} {} octave_config_info () -Return a structure containing configuration and installation -information. -@end deftypefn - -@deftypefn {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 -@code{getrusage}: - -@table @code -@item -@item idrss -Unshared data size. +@DOCSTRING(isieee) -@item inblock -Number of block input operations. - -@item isrss -Unshared stack size. - -@item ixrss -Shared memory size. - -@item majflt -Number of major page faults. - -@item maxrss -Maximum data size. - -@item minflt -Number of minor page faults. - -@item msgrcv -Number of messages received. - -@item msgsnd -Number of messages sent. +@DOCSTRING(OCTAVE_VERSION) -@item nivcsw -Number of involuntary context switches. - -@item nsignals -Number of signals received. - -@item nswap -Number of swaps. - -@item nvcsw -Number of voluntary context switches. +@DOCSTRING(octave_config_info) -@item oublock -Number of block output operations. - -@item stime -A structure containing the system CPU time used. The structure has the -elements @code{sec} (seconds) @code{usec} (microseconds). - -@item utime -A structure containing the user CPU time used. The structure has the -elements @code{sec} (seconds) @code{usec} (microseconds). -@end table -@end deftypefn +@DOCSTRING(getrusage)
--- a/examples/make_int.cc +++ b/examples/make_int.cc @@ -1,6 +1,6 @@ /* -Copyright (C) 1996, 1997 John W. Eaton +Copyright (C) 1996 John W. Eaton This file is part of Octave. @@ -28,6 +28,7 @@ class ostream; +#include <octave/lo-mappers.h> #include <octave/lo-utils.h> #include <octave/mx-base.h> #include <octave/str-vec.h> @@ -35,7 +36,6 @@ #include <octave/defun-dld.h> #include <octave/error.h> #include <octave/gripes.h> -#include <octave/lo-mappers.h> #include <octave/oct-obj.h> #include <octave/ops.h> #include <octave/ov-base.h> @@ -85,8 +85,8 @@ bool is_defined (void) const { return true; } bool is_real_scalar (void) const { return true; } - octave_value all (void) const { return (scalar != 0); } - octave_value any (void) const { return (scalar != 0); } + octave_value all (void) const { return (double) (scalar != 0); } + octave_value any (void) const { return (double) (scalar != 0); } bool is_real_type (void) const { return true; } bool is_scalar_type (void) const { return true; } @@ -111,76 +111,54 @@ ComplexMatrix complex_matrix_value (bool = false) const { return ComplexMatrix (1, 1, Complex (scalar)); } - octave_value not (void) const { return octave_value (! scalar); } + octave_value not (void) const { return octave_value ((double) ! scalar); } - octave_value uminus (void) const { return octave_value (- scalar); } + octave_value uminus (void) const { return new octave_integer (- scalar); } - octave_value transpose (void) const { return octave_value (scalar); } + octave_value transpose (void) const { return new octave_integer (scalar); } - octave_value hermitian (void) const { return octave_value (scalar); } + octave_value hermitian (void) const { return new octave_integer (scalar); } void increment (void) { ++scalar; } void decrement (void) { --scalar; } - void print (ostream& os); - - int type_id (void) const { return t_id; } - - string type_name (void) const { return t_name; } - - static int static_type_id (void) { return t_id; } - - static void register_type (void) - { t_id = octave_value_typeinfo::register_type (t_name); } + void print (ostream& os, bool pr_as_read_syntax = false) const; private: int scalar; - static int t_id; + DECLARE_OCTAVE_ALLOCATOR - static const string t_name; + DECLARE_OV_TYPEID_FUNCTIONS_AND_DATA }; -int octave_integer::t_id = -1; - -const string octave_integer::t_name ("integer"); +void +octave_integer::print (ostream& os, bool pr_as_read_syntax) const +{ + octave_print_internal (os, scalar, pr_as_read_syntax); +} -void -octave_integer::print (ostream& os) -{ - octave_print_internal (os, scalar, false); -} +#ifdef DEFBINOP_OP +#undef DEFBINOP_OP +#endif + +#define DEFBINOP_OP(name, t1, t2, op) \ + BINOPDECL (name, a1, a2) \ + { \ + CAST_BINOP_ARGS (const octave_ ## t1&, const octave_ ## t2&); \ + return octave_value \ + (new octave_integer (v1.t1 ## _value () op v2.t2 ## _value ())); \ + } // integer by integer ops. -static octave_value -add (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () + v2.integer_value ()); -} - -static octave_value -sub (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); +DEFBINOP_OP (add, integer, integer, +) +DEFBINOP_OP (sub, integer, integer, -) +DEFBINOP_OP (mul, integer, integer, *) - return new octave_integer (v1.integer_value () - v2.integer_value ()); -} - -static octave_value -mul (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () * v2.integer_value ()); -} - -static octave_value -div (const octave_value& a1, const octave_value& a2) +DEFBINOP (div, integer, integer) { CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); @@ -192,8 +170,8 @@ return new octave_integer (v1.integer_value () / d); } -static octave_value -i_s_div (const octave_value& a1, const octave_value& a2) + +DEFBINOP (i_s_div, integer, scalar) { CAST_BINOP_ARGS (const octave_integer&, const octave_scalar&); @@ -205,8 +183,7 @@ return new octave_scalar (v1.double_value () / d); } -static octave_value -ldiv (const octave_value& a1, const octave_value& a2) +DEFBINOP (ldiv, integer, integer) { CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); @@ -218,64 +195,16 @@ return new octave_integer (v2.integer_value () / d); } -static octave_value -lt (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () < v2.integer_value ()); -} - -static octave_value -le (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () <= v2.integer_value ()); -} - -static octave_value -eq (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () == v2.integer_value ()); -} - -static octave_value -ge (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); +DEFBINOP_OP (lt, integer, integer, <) +DEFBINOP_OP (le, integer, integer, <=) +DEFBINOP_OP (eq, integer, integer, ==) +DEFBINOP_OP (ge, integer, integer, >=) +DEFBINOP_OP (gt, integer, integer, >) +DEFBINOP_OP (ne, integer, integer, !=) - return new octave_integer (v1.integer_value () >= v2.integer_value ()); -} - -static octave_value -gt (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () > v2.integer_value ()); -} +DEFBINOP_OP (el_mul, integer, integer, !=) -static octave_value -ne (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () != v2.integer_value ()); -} - -static octave_value -el_mul (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () * v2.integer_value ()); -} - -static octave_value -el_div (const octave_value& a1, const octave_value& a2) +DEFBINOP (el_div, integer, integer) { CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); @@ -287,8 +216,7 @@ return new octave_integer (v1.integer_value () / d); } -static octave_value -el_ldiv (const octave_value& a1, const octave_value& a2) +DEFBINOP (el_ldiv, integer, integer) { CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); @@ -300,21 +228,8 @@ return new octave_integer (v2.integer_value () / d); } -static octave_value -el_and (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () && v2.integer_value ()); -} - -static octave_value -el_or (const octave_value& a1, const octave_value& a2) -{ - CAST_BINOP_ARGS (const octave_integer&, const octave_integer&); - - return new octave_integer (v1.integer_value () || v2.integer_value ()); -} +DEFBINOP_OP (el_and, integer, integer, &&) +DEFBINOP_OP (el_or, integer, integer, ||) DEFUN_DLD (make_int, args, , "int_val = make_int (val)\n\ @@ -365,6 +280,33 @@ return retval; } +DEFUN_DLD (doit, args, , + "doit (I)") +{ + octave_value_list retval; + + if (args(0).type_name () == "integer") + { + // At this point, we know we have a handle for an octave_integer + // object, so we can peek at the representation and extract the + // data. + + const octave_value& rep = args(0).get_rep (); + + int my_value = ((const octave_integer&) rep) . integer_value (); + + message ("doit", "your lucky number is: %d", my_value); + } + else + gripe_wrong_type_arg ("doit", args(0)); + + return retval; +} + +DEFINE_OCTAVE_ALLOCATOR (octave_integer); + +DEFINE_OV_TYPEID_FUNCTIONS_AND_DATA (octave_integer, "integer"); + /* ;;; Local Variables: *** ;;; mode: C++ ***
--- a/scripts/ChangeLog +++ b/scripts/ChangeLog @@ -1,5 +1,16 @@ 1999-10-19 John W. Eaton <jwe@bevo.che.wisc.edu> + * time/asctime.m: Texinfoize help text. + * time/clock.m: Ditto. + * time/date.m: Ditto. + * miscellaneous/cputime.m: Ditto. + * miscellaneous/etime.m: Ditto. + * miscellaneous/is_leap_year.m: Ditto. + * miscellaneous/popen2.m: Ditto. + * miscellaneous/version.m: Ditto. + * miscellaneous/tic.m: Ditto. + * miscellaneous/toc.m: Just refer to tic.m. + * Makefile.in (dist, bin-dist): Use `$(MAKE) -C dir' instead of `cd dir; $(MAKE); cd ..'. ($(SUBDIRS)): Likewise.
--- a/scripts/miscellaneous/cputime.m +++ b/scripts/miscellaneous/cputime.m @@ -17,9 +17,18 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: cputime -## -## Get CPU time statistics. +## -*- texinfo -*- +## @deftypefn {Function File} {[@var{total}, @var{user}, @var{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, @code{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 @code{cputime} works by checking to see if the total +## CPU time used is nonzero. +## @end deftypefn ## Author: jwe
--- a/scripts/miscellaneous/etime.m +++ b/scripts/miscellaneous/etime.m @@ -17,11 +17,22 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: etime (t1, t0) -## -## Return the difference between t1 and t0 in seconds. The arguments -## are expected to be vectors in the form returned by clock (). -## +## -*- texinfo -*- +## @deftypefn {Function File} {} etime (@var{t1}, @var{t2}) +## Return the difference (in seconds) between two time values returned from +## @code{clock}. For example: +## +## @example +## t0 = clock (); +## # many computations later... +## elapsed_time = etime (clock (), t0); +## @end example +## +## @noindent +## will set the variable @code{elapsed_time} to the number of seconds since +## the variable @code{t0} was set. +## @end deftypefn + ## See also: tic, toc, clock, cputime ## Author: jwe
--- a/scripts/miscellaneous/is_leap_year.m +++ b/scripts/miscellaneous/is_leap_year.m @@ -17,10 +17,19 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: is_leap_year (year) -## -## Return 1 if the given year is a leap year; otherwise, return 0. -## With no arguments, use the current year. +## -*- texinfo -*- +## @deftypefn {Function File} {} is_leap_year (@var{year}) +## Return 1 if the given year is a leap year and 0 otherwise. If no +## arguments are provided, @code{is_leap_year} will use the current year. +## For example, +## +## @example +## @group +## is_leap_year (2000) +## @result{} 1 +## @end group +## @end example +## @end deftypefn ## Author: jwe
--- a/scripts/miscellaneous/popen2.m +++ b/scripts/miscellaneous/popen2.m @@ -17,26 +17,34 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS) -## -## Start a subprocess with two-way communication. COMMAND specifies -## the name of the command to start. ARGS is an array of strings -## containing options for COMMAND. IN and out are the file ids of the -## input and streams for the subprocess, and PID is the process id of -## the subprocess, or -1 if COMMAND could not be executed. -## -## Example: -## -## [in, out, pid] = popen2 ("sort", "-nr"); -## fputs (in, "these\n"); -## fputs (in, "are\n"); -## fputs (in, "some\n"); -## fputs (in, "strings\n"); -## fclose (in); -## while (isstr (s = fgets (out))) -## fputs (stdout, s); -## endwhile -## fclose (out); +## -*- texinfo -*- +## @deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) +## Start a subprocess with two-way communication. The name of the process +## is given by @var{command}, and @var{args} is an array of strings +## containing options for the command. The file identifiers for the input +## and output streams of the subprocess are returned in @var{in} and +## @var{out}. If execution of the command is successful, @var{pid} +## contains the process ID of the subprocess. Otherwise, @var{pid} is +## @minus{}1. +## +## For example, +## +## @example +## @group +## [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); +## @print{} are +## @print{} some +## @print{} strings +## @print{} these +## @end group +## @end example +## @end deftypefn ## Author: jwe
--- a/scripts/miscellaneous/tic.m +++ b/scripts/miscellaneous/tic.m @@ -17,11 +17,39 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: tic -## -## Set a wall-clock timer. -## -## See also: toc, clock, etime, cputime +## @deftypefn {Function File} {} tic () +## @deftypefnx {Function File} {} toc () +## These functions set and check a wall-clock timer. For example, +## +## @example +## tic (); +## # many computations later... +## elapsed_time = toc (); +## @end example +## +## @noindent +## will set the variable @code{elapsed_time} to the number of seconds since +## the most recent call to the function @code{tic}. +## +## If you are more interested in the CPU time that your process used, you +## should use the @code{cputime} function instead. The @code{tic} and +## @code{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, +## +## @example +## @group +## tic (); sleep (5); toc () +## @result{} 5 +## t = cputime (); sleep (5); cputime () - t +## @result{} 0 +## @end group +## @end example +## +## @noindent +## (This example also illustrates that the CPU timer may have a fairly +## coarse resolution.) +## @end deftypefn ## Author: jwe
--- a/scripts/miscellaneous/toc.m +++ b/scripts/miscellaneous/toc.m @@ -17,12 +17,7 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: toc -## -## Return the difference between the current wall-clock time and the -## time that the function tic () was last called, in seconds. -## -## See also: tic, clock, etime, cputime +## See tic. ## Author: jwe
--- a/scripts/miscellaneous/version.m +++ b/scripts/miscellaneous/version.m @@ -17,11 +17,11 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: version -## -## Return the Octave version number as a string. -## -## See also: OCTAVE_VERSION +## -*- texinfo -*- +## @deftypefn {Function File} {} version () +## Return Octave's version number as a string. This is also the value of +## the built-in variable @code{OCTAVE_VERSION}. +## @end deftypefn ## Author: jwe
--- a/scripts/time/asctime.m +++ b/scripts/time/asctime.m @@ -17,7 +17,20 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: asctime (TMSTRUCT) +## -*- texinfo -*- +## @deftypefn {Function File} {} asctime (@var{tm_struct}) +## Convert a time structure to a string using the following five-field +## format: Thu Mar 28 08:40:14 1996. For example, +## +## @example +## @group +## asctime (localtime (time ()) +## @result{} "Mon Feb 17 01:15:06 1997\n" +## @end group +## @end example +## +## This is equivalent to @code{ctime (time ())}. +## @end deftypefn ## Author: jwe
--- a/scripts/time/clock.m +++ b/scripts/time/clock.m @@ -17,11 +17,21 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: clock () -## -## Return current date and time in vector with elements -## -## [ year, month, day-of-month, hour, minute, second ] +## -*- texinfo -*- +## @deftypefn {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, +## +## @example +## @group +## clock () +## @result{} [ 1993, 8, 20, 4, 56, 1 ] +## @end group +## @end example +## +## The function clock is more accurate on systems that have the +## @code{gettimeofday} function. +## @end deftypefn ## Author: jwe
--- a/scripts/time/date.m +++ b/scripts/time/date.m @@ -17,9 +17,18 @@ ## Software Foundation, 59 Temple Place - Suite 330, Boston, MA ## 02111-1307, USA. -## usage: date () -## -## Return current date in a string, in the form `18-Jul-94'. +## -*- texinfo -*- +## @deftypefn {Function File} {} date () +## Return the date as a character string in the form DD-MMM-YY. For +## example, +## +## @example +## @group +## date () +## @result{} "20-Aug-93" +## @end group +## @end example +## @end deftypefn ## Author: jwe
--- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,5 +1,32 @@ 1999-10-19 John W. Eaton <jwe@bevo.che.wisc.edu> + * Makefile.in (stmp-pic): New target. + ($(PICOBJS)): Depend on stmp-pic, not pic. + + * ov.h (get_rep): New function. + + * help.cc (display_help_text): Pass definitions for VERSION, + OCTAVE_HOME, and TARGETHOSTTYPE to makeinfo. + + * DLD-FUNCTIONS/getgrent.cc: Texinfoize all doc strings. + * DLD-FUNCTIONS/getpwent.cc: Ditto. + * DLD-FUNCTIONS/getrusage.cc: Ditto. + * DLD-FUNCTIONS/time.cc: Ditto. + + * defaults.cc (EXEC_PATH, OCTAVE_VERSION): Texinfoize doc strings. + * dirfns.cc (Fcd, Fls, Fpwd, Freaddir, Fmkdir, Frmdir, Frename, + Fglob, Ffnmatch): Ditto. + * file-io.cc (Fpopen, Fpclose, Fumask): Ditto. + * sysdep.cc (Fgetenv, Fputenv, Fpause, Fsleep, Fusleep, Fisieee, + Ftilde_expand): Ditto. + * toplev.cc (Fcomputer, Fsystem, Foctave_config_info): Ditto. + * utils.cc (Ffile_in_path): Ditto. + * syscalls.cc (Fdup2, Fexec, Ffcntl, Ffork, Fgetpgrp, Fgetpid, + Fgetppid, Fgetegid, Fgetgid, Fgeteuid, Fgetuid, Fmkfifo, Fpipe, + Fstat, Funlink, Fwaitpid, F): Ditto. + (Flstat): Refer to stat for doc. + + * help.cc (looks_like_texinfo): New function. (display_help_text): Use it to see if the doc string looks like Texinfo source. If so, use makeinfo to format the text before
--- a/src/DLD-FUNCTIONS/getgrent.cc +++ b/src/DLD-FUNCTIONS/getgrent.cc @@ -65,9 +65,11 @@ } DEFUN_DLD (getgrent, args, , - "getgrent ()\n\ -\n\ -Read an entry from the group-file stream, opening it if necessary.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {@var{grp_struct} =} getgrent ()\n\ +Return an entry from the group database, opening it if necessary.\n\ +Once the end of the data has been reached, @code{getgrent} returns 0.\n\ +@end deftypefn") { octave_value_list retval; @@ -90,9 +92,12 @@ } DEFUN_DLD (getgrgid, args, , - "getgrgid (GID)\n\ -\n\ -Search for a group entry with a matching group ID.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {@var{grp_struct} =} getgrgid (@var{gid}).\n\ +Return the first entry from the group database with the group ID\n\ +@var{gid}. If the group ID does not exist in the database,\n\ +@code{getgrgid} returns 0.\n\ +@end deftypefn") { octave_value_list retval; @@ -127,9 +132,12 @@ } DEFUN_DLD (getgrnam, args, , - "getgrnam (NAME)\n\ -\n\ -Search for group entry with a matching group name.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {@var{grp_struct} =} getgrnam (@var{name})\n\ +Return the first entry from the group database with the group name\n\ +@var{name}. If the group name does not exist in the database,\n\ +@code{getgrname} returns 0.\n\ +@end deftypefn") { octave_value_list retval; @@ -157,9 +165,10 @@ } DEFUN_DLD (setgrent, args, , - "setgrent ()\n\ -\n\ -Rewind the group-file stream.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} setgrent ()\n\ +Return the internal pointer to the beginning of the group database.\n\ +@end deftypefn") { octave_value_list retval; @@ -182,9 +191,10 @@ } DEFUN_DLD (endgrent, args, , - "endgrent ()\n\ -\n\ -Close the group-file stream.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} endgrent ()\n\ +Close the group database.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/getpwent.cc +++ b/src/DLD-FUNCTIONS/getpwent.cc @@ -68,9 +68,12 @@ } DEFUN_DLD (getpwent, args, , - "getpwent ()\n\ -\n\ -Read an entry from the password-file stream, opening it if necessary.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {@var{pw_struct} = } getpwent ()\n\ +Return a structure containing an entry from the password database,\n\ +opening it if necessary. Once the end of the data has been reached,\n\ +@code{getpwent} returns 0.\n\ +@end deftypefn") { octave_value_list retval; @@ -93,9 +96,12 @@ } DEFUN_DLD (getpwuid, args, , - "getpwuid (UID)\n\ -\n\ -Search for a password entry with a matching user ID.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {@var{pw_struct} = } getpwuid (@var{uid}).\n\ +Return a structure containing the first entry from the password database\n\ +with the user ID @var{uid}. If the user ID does not exist in the\n\ +database, @code{getpwuid} returns 0.\n\ +@end deftypefn") { octave_value_list retval; @@ -130,9 +136,12 @@ } DEFUN_DLD (getpwnam, args, , - "getpwnam (NAME)\n\ -\n\ -Search for password entry with a matching username.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {@var{pw_struct} = } getpwnam (@var{name})\n\ +Return a structure containing the first entry from the password database\n\ +with the user name @var{name}. If the user name does not exist in the\n\ +database, @code{getpwname} returns 0.\n\ +@end deftypefn") { octave_value_list retval; @@ -160,9 +169,10 @@ } DEFUN_DLD (setpwent, args, , - "setpwent ()\n\ -\n\ -Rewind the password-file stream.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} setpwent ()\n\ +Return the internal pointer to the beginning of the password database.\n\ +@end deftypefn") { octave_value_list retval; @@ -185,9 +195,10 @@ } DEFUN_DLD (endpwent, args, , - "endpwent ()\n\ -\n\ -Close the password-file stream.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} endpwent ()\n\ +Close the password database.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/DLD-FUNCTIONS/getrusage.cc +++ b/src/DLD-FUNCTIONS/getrusage.cc @@ -67,9 +67,67 @@ // System resource functions. DEFUN_DLD (getrusage, , , - "getrusage ()\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} getrusage ()\n\ +Return a structure containing a number of statistics about the current\n\ +Octave process. Not all fields are available on all systems. If it is\n\ +not possible to get CPU time statistics, the CPU time slots are set to\n\ +zero. Other missing data are replaced by NaN. Here is a list of all\n\ +the possible fields that can be present in the structure returned by\n\ +@code{getrusage}:\n\ +\n\ +@table @code\n\ +@item idrss\n\ +Unshared data size.\n\ +\n\ +@item inblock\n\ +Number of block input operations.\n\ +\n\ +@item isrss\n\ +Unshared stack size.\n\ +\n\ +@item ixrss\n\ +Shared memory size.\n\ +\n\ +@item majflt\n\ +Number of major page faults.\n\ +\n\ +@item maxrss\n\ +Maximum data size.\n\ +\n\ +@item minflt\n\ +Number of minor page faults.\n\ \n\ -Return system resource statistics.") +@item msgrcv\n\ +Number of messages received.\n\ +\n\ +@item msgsnd\n\ +Number of messages sent.\n\ +\n\ +@item nivcsw\n\ +Number of involuntary context switches.\n\ +\n\ +@item nsignals\n\ +Number of signals received.\n\ +\n\ +@item nswap\n\ +Number of swaps.\n\ +\n\ +@item nvcsw\n\ +Number of voluntary context switches.\n\ +\n\ +@item oublock\n\ +Number of block output operations.\n\ +\n\ +@item stime\n\ +A structure containing the system CPU time used. The structure has the\n\ +elements @code{sec} (seconds) @code{usec} (microseconds).\n\ +\n\ +@item utime\n\ +A structure containing the user CPU time used. The structure has the\n\ +elements @code{sec} (seconds) @code{usec} (microseconds).\n\ +@end table\n\ +@end deftypefn") { Octave_map m; Octave_map tv_tmp;
--- a/src/DLD-FUNCTIONS/time.cc +++ b/src/DLD-FUNCTIONS/time.cc @@ -76,10 +76,13 @@ } DEFUN_DLD (time, args, , - "time ()\n\ -\n\ -Return current time. On Unix systems, this is the number of\n\ -seconds since the epoch.") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} time ()\n\ +Return the current time as the number of seconds since the epoch. The\n\ +epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan\n\ +1970. For example, on Monday February 17, 1997 at 07:15:06 CUT, the\n\ +value returned by @code{time} was 856163706.\n\ +@end deftypefn") { octave_value retval; @@ -92,11 +95,30 @@ } DEFUN_DLD (gmtime, args, , - "gmtime (TIME)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} gmtime (@var{t})\n\ +Given a value returned from time (or any nonnegative integer),\n\ +return a time structure corresponding to CUT. For example,\n\ \n\ -Given a value returned from time(), return a structure like that\n\ -returned from localtime() but with values corresponding to\n\ -Coordinated Universal Time (UTC).") +@example\n\ +@group\n\ +gmtime (time ())\n\ + @result{} @{\n\ + usec = 0\n\ + year = 97\n\ + mon = 1\n\ + mday = 17\n\ + sec = 6\n\ + zone = CST\n\ + min = 15\n\ + wday = 1\n\ + hour = 7\n\ + isdst = 0\n\ + yday = 47\n\ + @}\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -114,22 +136,30 @@ } DEFUN_DLD (localtime, args, , - "localtime (TIME)\n\ -\n\ -Given a value returned from time(), return a structure with\n\ -the following elements:\n\ + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} localtime (@var{t})\n\ +Given a value returned from time (or any nonnegative integer),\n\ +return a time structure corresponding to the local time zone.\n\ \n\ - usec : microseconds after the second (0, 999999)\n\ - sec : seconds after the minute (0, 61)\n\ - min : minutes after the hour (0, 59)\n\ - hour : hours since midnight (0, 23)\n\ - mday : day of the month (1, 31)\n\ - mon : months since January (0, 11)\n\ - year : years since 1900\n\ - wday : days since Sunday (0, 6)\n\ - yday : days since January 1 (0, 365)\n\ - isdst : daylight savings time flag\n\ - zone : time zone") +@example\n\ +@group\n\ +localtime (time ())\n\ + @result{} @{\n\ + usec = 0\n\ + year = 97\n\ + mon = 1\n\ + mday = 17\n\ + sec = 6\n\ + zone = CST\n\ + min = 15\n\ + wday = 1\n\ + hour = 1\n\ + isdst = 0\n\ + yday = 47\n\ + @}\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -147,7 +177,18 @@ } DEFUN_DLD (mktime, args, , - "mktime (TMSTRUCT)") + "-*- texinfo -*-\n\ +@deftypefn {Loadable Function} {} mktime (@var{tm_struct})\n\ +Convert a time structure corresponding to the local time to the number\n\ +of seconds since the epoch. For example,\n\ +\n\ +@example\n\ +@group\n\ +mktime (localtime (time ())\n\ + @result{} 856163706\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/Makefile.in +++ b/src/Makefile.in @@ -223,6 +223,14 @@ $(OCTAVE_LIBS) \ $(FLIBS) $(LEXLIB) $(TERMLIBS) $(LIBS) +stmp-pic: pic + @if [ -f stmp-pic ]; then \ + true; \ + else \ + echo "touch stmp-pic"; \ + touch stmp-pic; \ + fi + pic: @if [ -d pic ]; then \ true; \ @@ -257,7 +265,7 @@ liboctinterp.$(SHLEXT_VER): $(PICOBJ) $(SH_LD) $(SH_LDFLAGS) $(SONAME_FLAGS) -o $@ $^ -$(PICOBJ): pic +$(PICOBJ): stmp-pic builtins.cc: $(DEF_FILES) mkbuiltins @echo making $@ @@ -372,15 +380,13 @@ etags $(SOURCES) $(DLD_SRC) clean: - rm -f *.$(LIBEXT) *.o *.d *.df *.oct pic/*.o + rm -f *.$(LIBEXT) *.o *.d *.df *.oct pic/*.o stmp-pic rm -f builtins.cc ops.cc defaults.h oct-conf.h def-files var-files -rmdir pic if $(SHARED_LIBS); then rm -f *.$(SHLEXT_VER) *.$(SHLEXT); fi .PHONY: clean -mostlyclean: - rm -f *.o pic/*.o - -rmdir pic +mostlyclean: clean .PHONY: mostlyclean distclean: clean
--- a/src/defaults.cc +++ b/src/defaults.cc @@ -419,7 +419,30 @@ "name of the editor to be invoked by the edit_history command"); DEFVAR (EXEC_PATH, Vexec_path, exec_path, - "colon separated list of directories to search for programs to run"); + "-*- texinfo -*-\n\ +@defvr {Built-in Variable} EXEC_PATH\n\ +The variable @code{EXEC_PATH} is a colon separated list of directories\n\ +to search when executing subprograms. Its initial value is taken from\n\ +the environment variable @code{OCTAVE_EXEC_PATH} (if it exists) or\n\ +@code{PATH}, but that value can be overridden by the command line\n\ +argument @code{--exec-path PATH}, or by setting the value of\n\ +@code{EXEC_PATH} in a startup script. If the value of @code{EXEC_PATH}\n\ +begins (ends) with a colon, the directories\n\ +\n\ +@example\n\ +@group\n\ +@var{octave-home}/libexec/octave/site/exec/@var{arch}\n\ +@var{octave-home}/libexec/octave/@var{version}/exec/@var{arch}\n\ +@end group\n\ +@end example\n\ +\n\ +@noindent\n\ +are prepended (appended) to @code{EXEC_PATH}, where @var{octave-home}\n\ +is the top-level directory where all of Octave is installed\n\ +(the default value is @file{@value{OCTAVEHOME}}). If you don't specify\n\ +a value for @code{EXEC_PATH} explicitly, these special directories are\n\ +prepended to your shell path.\n\ +@end defvr"); DEFVAR (LOADPATH, Vload_path, loadpath, "colon separated list of directories to search for scripts.\n\ @@ -437,7 +460,10 @@ "top-level Octave installation directory"); DEFCONSTX ("OCTAVE_VERSION", SBV_OCTAVE_VERSION, OCTAVE_VERSION, - "Octave version"); + "-*- texinfo -*-\n\ +@defvr\n\ +The version number of Octave, as a string.\n\ +@end defvr"); } DEFUN (rehash, , ,
--- a/src/dirfns.cc +++ b/src/dirfns.cc @@ -80,11 +80,22 @@ } DEFUN_TEXT (cd, args, , - "cd [dir]\n\ + "-*- texinfo -*-\n\ +@deffn {Command} cd dir\n\ +@deffnx {Command} chdir dir\n\ +Change the current working directory to @var{dir}. If @var{dir} is\n\ +omitted, the current directory is changed to the users home\n\ +directory. For example,\n\ \n\ -change current working directory\n\ -if no arguments are given, the current directory is changed to the\n\ -users home directory") +@example\n\ +cd ~/octave\n\ +@end example\n\ +\n\ +@noindent\n\ +Changes the current working directory to @file{~/octave}. If the\n\ +directory does not exist, an error message is printed and the working\n\ +directory is not changed.\n\ +@end deffn") { octave_value_list retval; @@ -127,9 +138,22 @@ } DEFUN_TEXT (ls, args, , - "ls [options]\n\ + "-*- texinfo -*-\n\ +@deffn {Command} ls options\n\ +@deffnx {Command} dir options\n\ +List directory contents. For example,\n\ \n\ -print a directory listing") +@example\n\ +ls -l\n\ + @print{} total 12\n\ + @print{} -rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m\n\ + @print{} -rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m\n\ +@end example\n\ +\n\ +The @code{dir} and @code{ls} commands are implemented by calling your\n\ +system's directory listing command, so the available options may vary\n\ +from system to system.\n\ +@end deffn") { octave_value_list retval; @@ -194,7 +218,10 @@ DEFALIAS (dir, ls); DEFUN (pwd, , nargout, - "pwd (): print current working directory") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} pwd ()\n\ +Return the current working directory.\n\ +@end deftypefn") { octave_value_list retval; @@ -214,13 +241,15 @@ } DEFUN (readdir, args, , - "[FILES, STATUS, MSG] = readdir (NAME)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir})\n\ +Return names of the files in the directory @var{dir} as an array of\n\ +strings. If an error occurs, return an empty matrix in @var{files}.\n\ \n\ -Return an array of strings containing the list of all files in the\n\ -named directory in FILES, or an empty matrix if an error occurs\n\ -\n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -260,12 +289,14 @@ // mode. DEFUN (mkdir, args, , - "[STATUS, MSG] = mkdir (NAME)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkdir (@var{dir})\\n\ +Create a directory named @var{dir}.\n\ \n\ -Create the directory named by NAME.\n\ -\n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -298,12 +329,14 @@ } DEFUN (rmdir, args, , - "[STATUS, MSG] = rmdir (NAME)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rmdir (@var{dir})\n\ +Remove the directory named @var{dir}.\n\ \n\ -Remove the directory named by NAME.\n\ -\n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -335,12 +368,14 @@ } DEFUN (rename, args, , - "[STATUS, MSG] = rename (FROM, TO)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new})\n\ +Change the name of file @var{old} to @var{new}.\n\ \n\ -Rename a file.\n\ -\n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -379,12 +414,23 @@ } DEFUN (glob, args, , - "glob (PATTERN)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} glob (@var{pattern})\n\ +Given an array of strings in @var{pattern}, return the list of file\n\ +names that any of them, or an empty string if no patterns match. Tilde\n\ +expansion is performed on each of the patterns before looking for\n\ +matching file names. For example,\n\ \n\ -Given an array of strings in PATTERN, return the list of file names\n\ -that any of them, or an empty string if no patterns match. Tilde\n\ -expansion is performed on each of the patterns before looking for\n\ -matching file names.") +@example\n\ +@group\n\ +glob (\"/vm*\")\n\ + @result{} \"/vmlinuz\"\n\ +@end group\n\ +@end example\n\ +\n\ +Note that multiple values are returned in a string matrix with the fill\n\ +character set to ASCII NUL.\n\ +@end deftypefn") { octave_value retval; @@ -413,11 +459,19 @@ } DEFUN (fnmatch, args, , - "fnmatch (PATTERN, STRING)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string})\n\ +Return 1 or zero for each element of @var{string} that matches any of\n\ +the elements of the string array @var{pattern}, using the rules of\n\ +filename pattern matching. For example,\n\ \n\ -Return 1 or zero for each element of STRING that matches any of the\n\ -elements of the string array PATTERN, using the rules of filename\n\ -pattern matching.") +@example\n\ +@group\n\ +fnmatch (\"a*b\", [\"ab\"; \"axyzb\"; \"xyzab\"])\n\ + @result{} [ 1; 1; 0 ]\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value retval;
--- a/src/file-io.cc +++ b/src/file-io.cc @@ -1205,12 +1205,37 @@ } DEFUN (popen, args, , - "FILENUM = popen (FILENAME, MODE)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {fid =} popen (@var{command}, @var{mode})\n\ +Start a process and create a pipe. The name of the command to run is\n\ +given by @var{command}. The file identifier corresponding to the input\n\ +or output stream of the process is returned in @var{fid}. The argument\n\ +@var{mode} may be\n\ +\n\ +@table @code\n\ +@item \"r\"\n\ +The pipe will be connected to the standard output of the process, and\n\ +open for reading.\n\ \n\ - start a process and create a pipe. Valid values for mode are:\n\ +@item \"w\"\n\ +The pipe will be connected to the standard input of the process, and\n\ +open for writing.\n\ +@end table\n\ +\n\ +For example,\n\ \n\ - \"r\" : connect stdout of process to pipe\n\ - \"w\" : connect stdin of process to pipe") +@example\n\ +@group\n\ +fid = popen (\"ls -ltr / | tail -3\", \"r\");\n\ +while (isstr (s = fgets (fid)))\n\ + fputs (stdout, s);\n\ +endwhile\n\ + @print{} drwxr-xr-x 33 root root 3072 Feb 15 13:28 etc\n\ + @print{} drwxr-xr-x 3 root root 1024 Feb 15 13:28 lib\n\ + @print{} drwxrwxrwt 15 root root 2048 Feb 17 14:53 tmp\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value retval = -1.0; @@ -1254,9 +1279,11 @@ } DEFUN (pclose, args, , - "pclose (FILENUM)\n\ -\n\ - Close a pipe and terminate the associated process") + "-*- texifno -*-\n\ +@deftypefn {Built-in Function} {} pclose (@var{fid})\n\ +Close a file identifier that was opened by @code{popen}. You may also\n\ +use @code{fclose} for the same purpose.\n\ +@end deftypefn") { double retval = -1.0; @@ -1329,13 +1356,13 @@ } DEFUN (umask, args, , - "umask (MASK)\n\ -\n\ -Change the file permission mask for file creation for the current\n\ -process. MASK is an integer, interpreted as an octal number. If\n\ -successful, returns the previous value of the mask (as an integer to\n\ -be interpreted as an octal number); otherwise an error message is\n\ -printed.") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} umask (@var{mask})\n\ +Set the permission mask for file creation. The parameter @var{mask}\n\ + is an integer, interpreted as an octal number. If successful,\n\ + returns the previous value of the mask (as an integer to be\n\ + interpreted as an octal number); otherwise an error message is printed.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/help.cc +++ b/src/help.cc @@ -68,6 +68,7 @@ #include "unwind-prot.h" #include "utils.h" #include "variables.h" +#include "version.h" // Name of the info file specified on command line. // (--info-file file) @@ -704,10 +705,16 @@ cols = 72; ostrstream buf; - buf << "sed 's/^[#%]+ *//'" - << " | makeinfo --fill-column " << cols - << " --no-warn --no-validate --no-headers --force --output " - << tmp_file_name + buf << "sed 's/^[#%]+ *//' | makeinfo" + << " -D VERSION \"" << OCTAVE_VERSION << "\"" + << " -D OCTAVE_HOME \"" << OCTAVE_PREFIX << "\"" + << " -D TARGETHOSTTYPE \"" << CANONICAL_HOST_TYPE << "\"" + << " --fill-column " << cols + << " --no-warn" + << " --no-validate" + << " --no-headers" + << " --force" + << " --output " << tmp_file_name << ends; char *cmd = buf.str ();
--- a/src/ov.h +++ b/src/ov.h @@ -477,6 +477,8 @@ const octave_value&, const octave_value&); + const octave_value& get_rep (void) const { return *rep; } + protected: octave_value (const octave_xvalue&) : rep (0) { } @@ -609,16 +611,16 @@ public: \ int type_id (void) const { return t_id; } \ string type_name (void) const { return t_name; } \ - static int static_type_id (void) { return t_id; } \ + static volatile int static_type_id (void) { return t_id; } \ static void register_type (void) \ { t_id = octave_value_typeinfo::register_type (t_name); } \ \ private: \ - static int t_id; \ + static volatile int t_id; \ static const string t_name; #define DEFINE_OV_TYPEID_FUNCTIONS_AND_DATA(t, n) \ - int t::t_id (-1); \ + volatile int t::t_id (-1); \ const string t::t_name (n) // If TRUE, allow assignments like
--- a/src/syscalls.cc +++ b/src/syscalls.cc @@ -90,12 +90,14 @@ } DEFUN (dup2, args, , - "[FID, MSG] = dup2 (OLD, NEW)\n\ -\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{fid}, @var{msg}] =} dup2 (@var{old}, @var{new})\n\ Duplicate a file descriptor.\n\ \n\ -If successful, FID is greater than zero and contains the new file ID.\n\ -Otherwise, FID is negative and MSG contains a system-dependent error message.") +If successful, @var{fid} is greater than zero and contains the new file\n\ +ID. Otherwise, @var{fid} is negative and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -136,12 +138,23 @@ } DEFUN (exec, args, , - "[STATUS, MSG] = exec (FILE, ARGS)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args})\n\ +Replace current process with a new process. Calling @code{exec} without\n\ +first calling @code{fork} will terminate your current Octave process and\n\ +replace it with the program named by @var{file}. For example,\n\ \n\ -Replace current process with a new process.\n\ +@example\n\ +exec (\"ls\" \"-l\")\n\ +@end example\n\ \n\ -If successful, exec does not return. If exec does return, status will\n\ -be nonzero, and MSG will contain a system-dependent error message.") +@noindent\n\ +will run @code{ls} and return you to your shell prompt.\n\ +\n\ +If successful, @code{exec} does not return. If @code{exec} does return,\n\ +@var{err} will be nonzero, and @var{msg} will contain a system-dependent\n\ +error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -203,12 +216,58 @@ } DEFUN (fcntl, args, , - "[STATUS, MSG] = fcntl (FID, REQUEST, ARGUMENT)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg})\n\ +Change the properties of the open file @var{fid}. The following values\n\ +may be passed as @var{request}:\n\ +\n\ +@vtable @code\n\ +@item F_DUPFD\n\ +Return a duplicate file descriptor.\n\ +\n\ +@item F_GETFD\n\ +Return the file descriptor flags for @var{fid}.\n\ +\n\ +@item F_SETFD\n\ +Set the file descriptor flags for @var{fid}.\n\ +\n\ +@item F_GETFL\n\ +Return the file status flags for @var{fid}. The following codes may be\n\ +returned (some of the flags may be undefined on some systems).\n\ +\n\ +@vtable @code\n\ +@item O_RDONLY\n\ +Open for reading only.\n\ +\n\ +@item O_WRONLY\n\ +Open for writing only.\n\ \n\ -Control open file descriptors.\n\ +@item O_RDWR\n\ +Open for reading and writing.\n\ +\n\ +@item O_APPEND\n\ +Append on each write.\n\ +\n\ +@item O_NONBLOCK\n\ +Nonblocking mode.\n\ +\n\ +@item O_SYNC\n\ +Wait for writes to complete.\n\ \n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +@item O_ASYNC\n\ +Asynchronous I/O.\n\ +@end vtable\n\ +\n\ +@item F_SETFL\n\ +Set the file status flags for @var{fid} to the value specified by\n\ +@var{arg}. The only flags that can be changed are @code{O_APPEND} and\n\ +@code{O_NONBLOCK}.\n\ +@end vtable\n\ +\n\ +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -248,13 +307,27 @@ } DEFUN (fork, args, , - "[PID, MSG] = fork ()\n\ -\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} fork ()\n\ Create a copy of the current process.\n\ \n\ -If successful, PID is either the process ID and you are in the parent,\n\ -or 0, and you are in the child. If PID is less than zero, an error\n\ -has occured, and MSG contains a system-dependent error message.") +Fork can return one of the following values:\n\ +\n\ +@table @asis\n\ +@item > 0\n\ +You are in the parent process. The value returned from @code{fork} is\n\ +the process id of the child process. You should probably arrange to\n\ +wait for any child processes to exit.\n\ +\n\ +@item 0\n\ +You are in the child process. You can call @code{exec} to start another\n\ +process. If that fails, you should probably call @code{exit}.\n\ +\n\ +@item < 0\n\ +The call to @code{fork} failed for some reason. You must take evasive\n\ +action. A system dependent error message will be waiting in @var{msg}.\n\ +@end table\n\ +@end deftypefn") { octave_value_list retval; @@ -279,7 +352,10 @@ } DEFUN (getpgrp, args, , - "pgid = getpgrp (): return the process group id of the current process") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {pgid =} getpgrp ()\n\ +Return the process group id of the current process.\n\ +@end deftypefn") { octave_value_list retval; @@ -302,7 +378,10 @@ } DEFUN (getpid, args, , - "pid = getpid (): return the process id of the current process") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {pid =} getpid ()\n\ +Return the process id of the current process.\n\ +@end deftypefn") { double retval = -1.0; @@ -317,7 +396,10 @@ } DEFUN (getppid, args, , - "pid = getppid (): return the process id of the parent process") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {pid =} getppid ()\n\ +Return the process id of the parent process.\n\ +@end deftypefn") { double retval = -1.0; @@ -332,7 +414,10 @@ } DEFUN (getegid, args, , - "gid = getegid (): return the effective group id of the current process") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {egid =} getegid ()\n\ +Return the effective group id of the current process.\n\ +@end deftypefn") { double retval = -1.0; @@ -347,7 +432,10 @@ } DEFUN (getgid, args, , - "gid = getgid (): return the real group id of the current process") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {gid =} getgid ()\n\ +Return the real group id of the current process.\n\ +@end deftypefn") { double retval = -1.0; @@ -362,7 +450,10 @@ } DEFUN (geteuid, args, , - "uid = geteuid (): return the effective user id of the current process") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {euid =} geteuid ()\n\ +Return the effective user id of the current process.\n\ +@end deftypefn") { double retval = -1.0; @@ -377,7 +468,10 @@ } DEFUN (getuid, args, , - "uid = getuid (): return the real user id of the current process") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {uid =} getuid ()\n\ +Return the real user id of the current process.\n\ +@end deftypefn") { double retval = -1.0; @@ -392,11 +486,7 @@ } DEFUN (lstat, args, , - "[S, ERR, MSG] = lstat (NAME)\n\ -\n\ -Like [S, ERR, MSG] = stat (NAME), but if NAME refers to a symbolic\n\ -link, returns information about the link itself, not the file that it\n\ -points to.") + "See stat.") { octave_value_list retval; @@ -428,13 +518,16 @@ return retval; } + + DEFUN (mkfifo, args, , - "[STATUS, MSG] = mkfifo (NAME, MODE)\n\ + "@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkfifo (@var{name})\n\ +Create a @var{fifo} special file named @var{name} with file mode @var{mode}\n\\n\ \n\ -Create a FIFO special file named NAME with file mode MODE\n\ -\n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -475,13 +568,15 @@ } DEFUN (pipe, args, , - "[FILE_LIST, STATUS, MSG] = pipe (): create an interprocess channel.\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{file_ids}, @var{err}, @var{msg}] =} pipe ()\n\ +Create a pipe and return the vector @var{file_ids}, which corresponding\n\ +to the reading and writing ends of the pipe.\n\ \n\ -Return the file objects corresponding to the reading and writing ends of\n\ -the pipe, as a two-element list.\n\ -\n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -528,30 +623,92 @@ } DEFUN (stat, args, , - "[S, ERR, MSG] = stat (NAME)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file})\n\ +@deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file})\n\ +Return a structure @var{s} containing the following information about\n\ +@var{file}.\n\ +\n\ +@table @code\n\ +@item dev\n\ +ID of device containing a directory entry for this file.\n\ +\n\ +@item ino\n\ +File number of the file.\n\ +\n\ +@item modestr\n\ +File mode, as a string of ten letters or dashes as would be returned by\n\ +@kbd{ls -l}.\n\ +\n\ +@item nlink\n\ +Number of links.\n\ \n\ - Given the name of a file, return a structure S with the following\n\ - elements:\n\ +@item uid\n\ +User ID of file's owner.\n\ +\n\ +@item gid\n\ +Group ID of file's group.\n\ +\n\ +@item rdev\n\ +ID of device for block or character special files.\n\ +\n\ +@item size\n\ +Size in bytes.\n\ +\n\ +@item atime\n\ +Time of last access in the same form as time values returned from\n\ +@code{time}. @xref{Timing Utilities}.\n\ +\n\ +@item mtime\n\ +Time of last modification in the same form as time values returned from\n\ +@code{time}. @xref{Timing Utilities}.\n\ \n\ - dev : id of device containing a directory entry for this file\n\ - ino : file number of the file\n\ - modestr : file mode, as a string of ten letters or dashes as in ls -l\n\ - nlink : number of links\n\ - uid : user id of file's owner\n\ - gid : group id of file's group \n\ - rdev : id of device for block or character special files\n\ - size : size in bytes\n\ - atime : time of last access\n\ - mtime : time of last modification\n\ - ctime : time of last file status change\n\ - blksize : size of blocks in the file\n\ - blocks : number of blocks allocated for file\n\ +@item ctime\n\ +Time of last file status change in the same form as time values\n\ +returned from @code{time}. @xref{Timing Utilities}.\n\ +\n\ +@item blksize\n\ +Size of blocks in the file.\n\ +\n\ +@item blocks\n\ +Number of blocks allocated for file.\n\ +@end table\n\ +\n\ +If the call is successful @var{err} is 0 and @var{msg} is an empty\n\ +string. If the file does not exist, or some other error occurs, @var{s}\n\ +is an empty matrix, @var{err} is @minus{}1, and @var{msg} contains the\n\ +corresponding system error message.\n\ +\n\ +If @var{file} is a symbolic link, @code{stat} will return information\n\ +about the actual file the is referenced by the link. Use @code{lstat}\n\ +if you want information about the symbolic link itself.\n\ +\n\ +For example,\n\ \n\ - If the call is successful, ERR is 0 and MSG is an empty string.\n\ -\n\ - If the file does not exist, or some other error occurs, S is an\n\ - empty matrix, ERR is -1, and MSG contains the corresponding\n\ - system error message.") +@example\n\ +@group\n\ +[s, err, msg] = stat (\"/vmlinuz\")\n\ + @result{} s =\n\ + @{\n\ + atime = 855399756\n\ + rdev = 0\n\ + ctime = 847219094\n\ + uid = 0\n\ + size = 389218\n\ + blksize = 4096\n\ + mtime = 847219094\n\ + gid = 6\n\ + nlink = 1\n\ + blocks = 768\n\ + modestr = -rw-r--r--\n\ + ino = 9316\n\ + dev = 2049\n\ + @}\n\ + @result{} err = 0\n\ + @result{} msg = \n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -584,12 +741,14 @@ } DEFUN (unlink, args, , - "[STATUS, MSG] = unlink (NAME)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} unlink (@var{file})\n\ +Delete the file named @var{file}.\n\ \n\ -Delete the file NAME\n\ -\n\ -If successful, STATUS is 0 and MSG is an empty string. Otherwise,\n\ -STATUS is nonzero and MSG contains a system-dependent error message.") +If successful, @var{err} is 0 and @var{msg} is an empty string.\n\ +Otherwise, @var{err} is nonzero and @var{msg} contains a\n\ +system-dependent error message.\n\ +@end deftypefn") { octave_value_list retval; @@ -621,31 +780,45 @@ } DEFUN (waitpid, args, , - "[PID, MSG] = waitpid (PID, OPTIONS)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} waitpid (@var{pid}, @var{options})\n\ +Wait for process @var{pid} to terminate. The @var{pid} argument can be:\n\ \n\ -Wait for process PID to terminate\n\ -\n\ - PID can be:\n\ +@table @asis\n\ +@item @minus{}1\n\ +Wait for any child process.\n\ \n\ - -1 : wait for any child process\n\ - 0 : wait for any child process whose process group ID is equal to\n\ - that of the Octave interpreter process.\n\ - > 0 : wait for termination of the child process with ID PID.\n\ +@item 0\n\ +Wait for any child process whose process group ID is equal to that of\n\ +the Octave interpreter process.\n\ \n\ - OPTIONS is:\n\ +@item > 0\n\ +Wait for termination of the child process with ID @var{pid}.\n\ +@end table\n\ +\n\ +The @var{options} argument can be:\n\ \n\ - 0 : wait until signal is received or a child process exits (this\n\ - is the default if the OPTIONS argument is missing) \n\ - 1 : do not hang if status is not immediately available\n\ - 2 : report the status of any child processes that are\n\ - stopped, and whose status has not yet been reported\n\ - since they stopped\n\ - 3 : implies both 1 and 2\n\ +@table @asis\n\ +@item 0\n\ +Wait until signal is received or a child process exits (this is the\n\ +default if the @var{options} argument is missing).\n\ +\n\ +@item 1\n\ +Do not hang if status is not immediately available.\n\ \n\ -If successful, PID is greater than 0 and contains the process ID of\n\ -the child process that exited and MSG is an empty string.\n\ -Otherwise, PID is less than zero and MSG contains a system-dependent\n\ -error message.") +@item 2\n\ +Report the status of any child processes that are stopped, and whose\n\ +status has not yet been reported since they stopped.\n\ +\n\ +@item 3\n\ +Implies both 1 and 2.\n\ +@end table\n\ +\n\ +If the returned value of @var{pid} is greater than 0, it is the process\n\ +ID of the child process that exited. If an error occurs, @var{pid} will\n\ +be less than zero and @var{msg} will contain a system-dependent error\n\ +message.\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/sysdep.cc +++ b/src/sysdep.cc @@ -330,7 +330,17 @@ DEFALIAS (home, clc); DEFUN (getenv, args, , - "getenv (STRING): get environment variable values") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} getenv (@var{var})\n\ +Return the value of the environment variable @var{var}. For example,\n\ +\n\ +@example\n\ +getenv (\"PATH\")\n\ +@end example\n\ +\n\ +@noindent\n\ +returns a string containing the value of your path.\n\ +@end deftypefn") { octave_value_list retval; @@ -350,7 +360,10 @@ } DEFUN (putenv, args, , - "putenv (VAR, VALUE): define environment variable VAR=VALUE") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} putenv (@var{var}, @var{value})\n\ +Set the value of the environment variable @var{var} to @var{value}.\n\ +@end deftypefn") { octave_value_list retval; @@ -398,7 +411,22 @@ } DEFUN (pause, args, , - "pause (seconds): suspend program execution") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} pause (@var{seconds})\n\ +Suspend the execution of the program. If invoked without any arguments,\n\ +Octave waits until you type a character. With a numeric argument, it\n\ +pauses for the given number of seconds. For example, the following\n\ +statement prints a message and then waits 5 seconds before clearing the\n\ +screen.\n\ +\n\ +@example\n\ +@group\n\ +fprintf (stderr, \"wait please...\n\");\n\ +pause (5);\n\ +clc;\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -441,7 +469,10 @@ } DEFUN (sleep, args, , - "sleep (seconds): suspend program execution") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} sleep (@var{seconds})\n\ +Suspend the execution of the program for the given number of seconds.\n\ +@end deftypefn") { octave_value_list retval; @@ -468,7 +499,13 @@ } DEFUN (usleep, args, , - "usleep (microseconds): suspend program execution") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} usleep (@var{microseconds})\n\ +Suspend the execution of the program for the given number of\n\ +microseconds. On systems where it is not possible to sleep for periods\n\ +of time less than one second, @code{usleep} will pause the execution for\n\ +@code{round (@var{microseconds} / 1e6)} seconds.\n\ +@end deftypefn") { octave_value_list retval; @@ -506,7 +543,11 @@ // point functions really work. DEFUN (isieee, , , - "isieee (): return 1 if host uses IEEE floating point") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} isieee ()\n\ +Return 1 if your computer claims to conform to the IEEE standard for\n\ +floating point calculations.\n\ +@end deftypefn") { oct_mach_info::float_format flt_fmt = oct_mach_info::native_float_format (); @@ -516,7 +557,25 @@ } DEFUN (tilde_expand, args, , - "tilde_expand (STRING): perform tilde expansion on STRING") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} tilde_expand (@var{string})\n\ +Performs tilde expansion on @var{string}. If @var{string} begins with a\n\ +tilde character, (@samp{~}), all of the characters preceding the first\n\ +slash (or all characters, if there is no slash) are treated as a\n\ +possible user name, and the tilde and the following characters up to the\n\ +slash are replaced by the home directory of the named user. If the\n\ +tilde is followed immediately by a slash, the tilde is replaced by the\n\ +home directory of the user running Octave. For example,\n\ +\n\ +@example\n\ +@group\n\ +tilde_expand (\"~joeuser/bin\")\n\ + @result{} \"/home/joeuser/bin\"\n\ +tilde_expand (\"~/bin\")\n\ + @result{} \"/home/jwe/bin\"\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;
--- a/src/toplev.cc +++ b/src/toplev.cc @@ -196,9 +196,23 @@ } DEFUN (computer, args, nargout, - "computer ():\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} computer ()\n\ +Print or return a string of the form @var{cpu}-@var{vendor}-@var{os}\n\ +that identifies the kind of computer Octave is running on. If invoked\n\ +with an output argument, the value is returned instead of printed. For\n\ +example,\n\ \n\ -Have Octave ask the system, \"What kind of computer are you?\"") +@example\n\ +@group\n\ +computer ()\n\ + @print{} i586-pc-linux-gnu\n\ +\n\ +x = computer ()\n\ + @result{} x = \"i586-pc-linux-gnu\"\n\ +@end group\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval; @@ -357,27 +371,46 @@ } DEFUN (system, args, nargout, - "system (STRING [, RETURN_OUTPUT] [, TYPE])\n\ -\n\ -Execute the shell command specified by STRING.\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} system (@var{string}, @var{return_output}, @var{type})\n\ +Execute a shell command specified by @var{string}. The second\n\ +argument is optional. If @var{type} is @code{\"async\"}, the process\n\ +is started in the background and the process id of the child process\n\ +is returned immediately. Otherwise, the process is started, and\n\ +Octave waits until it exits. If @var{type} argument is omitted, a\n\ +value of @code{\"sync\"} is assumed.\n\ \n\ -If TYPE is \"async\", the process is started in the background and the\n\ -pid of the child proces is returned immediately. Otherwise, the\n\ -process is started, and Octave waits until it exits. If TYPE argument\n\ -is omitted, a value of \"sync\" is assumed.\n\ -\n\ -If NARGIN == 2 (the actual value of RETURN_OUTPUT is irrelevant) and\n\ -the subprocess is started synchronously, or if system() is called with\n\ -NARGIN == 1 and NARGOUT > 0, the output from the command is returned.\n\ +If two input arguments are given (the actual value of\n\ +@var{return_output} is irrelevant) and the subprocess is started\n\ +synchronously, or if @var{system} is called with one input argument and\n\ +one or more output arguments, the output from the command is returned.\n\ Otherwise, if the subprocess is executed synchronously, it's output is\n\ sent to the standard output. To send the output of a command executed\n\ -with system() through the pager, use a command like\n\ +with @var{system} through the pager, use a command like\n\ \n\ - disp (system (CMD, 1));\n\ +@example\n\ +disp (system (cmd, 1));\n\ +@end example\n\ \n\ +@noindent\n\ or\n\ \n\ - printf (\"%s\\n\", system (CMD, 1));") +@example\n\ +printf (\"%s\n\", system (cmd, 1));\n\ +@end example\n\ +\n\ +The @code{system} function can return two values. The first is any\n\ +output from the command that was written to the standard output stream,\n\ +and the second is the output status of the command. For example,\n\ +\n\ +@example\n\ +[output, status] = system (\"echo foo; exit 2\");\n\ +@end example\n\ +\n\ +@noindent\n\ +will set the variable @code{output} to the string @samp{foo}, and the\n\ +variable @code{status} to the integer @samp{2}.\n\ +@end deftypefn") { octave_value_list retval; @@ -533,13 +566,15 @@ } DEFUN (octave_config_info, args, , - "octave_config_info (OPTION)\n\ + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} octave_config_info (@var{option})\n\ +Return a structure containing configuration and installation\n\ +information for Octave.\n\ \n\ -If OPTION is a string, return the configuration information for the\n\ +if @var{option} is a string, return the configuration information for the\n\ specified option.\n\ \n\ -With no arguments, return a structure containing configuration\n\ -information.") +@end deftypefn") { octave_value retval;
--- a/src/utils.cc +++ b/src/utils.cc @@ -259,7 +259,21 @@ } DEFUN (file_in_path, args, , - "file_in_path (PATH, NAME)") + "-*- texinfo -*-\n\ +@deftypefn {Built-in Function} {} file_in_path (@var{path}, @var{file})\n\ +Return the absolute name name of @var{file} if it can be found in\n\ +@var{path}. The value of @var{path} should be a colon-separated list of\n\ +directories in the format described for the built-in variable\n\ +@code{LOADPATH}.\n\ +\n\ +If the file cannot be found in the path, an empty matrix is returned.\n\ +For example,\n\ +\n\ +@example\n\ +file_in_path (LOADPATH, \"nargchk.m\")\n\ + @result{} \"@value{OCTAVEHOME}/share/octave/2.0/m/general/nargchk.m\"\n\ +@end example\n\ +@end deftypefn") { octave_value_list retval;