System Utilities
****************

This chapter describes the functions that are available to allow you to get information about what is happening outside of Octave, while it is still running, and use this information in your program.  For example, you can get information about environment variables, the current time, and even start other programs from the Octave prompt.

Timing Utilities
================

Octave's core set of functions for manipulating time values are patterned after the corresponding functions from the standard C library. Several of these functions use a data structure for time that includes the following elements:

usec
     Microseconds after the second (0-999999).

sec
     Seconds after the minute (0-60).  This number can be 60 to account for leap seconds.

min
     Minutes after the hour (0-59).

hour
     Hours since midnight (0-23).

mday
     Day of the month (1-31).

mon
     Months since January (0-11).

year
     Years since 1900.

wday
     Days since Sunday (0-6).

yday
     Days since January 1 (0-365).

isdst
     Daylight saving time flag.

gmtoff
     Seconds offset from UTC.

zone
     Time zone.

In the descriptions of the following functions, this structure is referred to as a TM_STRUCT.

 -- SECONDS =: time ()
     Return the current time as the number of seconds since the epoch.

     The epoch is referenced to 00:00:00 UTC (Coordinated Universal Time) 1 Jan 1970.  For example, on Monday February 17, 1997 at 07:15:06 UTC, the value returned by time was 856163706. strftime, strptime, localtime, gmtime, mktime, now, date, clock, datenum, datestr, datevec, calendar, weekday

 -- t =: now ()
     Return the current local date/time as a serial day number (see datenum).

     The integral part, floor (now) corresponds to the number of days between today and Jan 1, 0000.

     The fractional part, rem (now, 1) corresponds to the current time. clock, date, datenum

 -- STR =: ctime (T)
     Convert a value returned from time (or any other non-negative integer), to the local time and return a string of the same form as asctime.

     The function ctime (time) is equivalent to asctime (localtime (time)).  For example:

          ctime (time ())
             => "Mon Feb 17 01:15:06 1997\n"

     asctime, time, localtime

 -- TM_STRUCT =: gmtime (T)
     Given a value returned from time, or any non-negative integer, return a time structure corresponding to UTC (Coordinated Universal Time).

     For example:

          gmtime (time ())
               => {
                     usec = 0
                     sec = 6
                     min = 15
                     hour = 7
                     mday = 17
                     mon = 1
                     year = 97
                     wday = 1
                     yday = 47
                     isdst = 0
                     gmtoff = 0
                     zone = GMT
                  }

     strftime, strptime, localtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday

 -- TM_STRUCT =: localtime (T)
     Given a value returned from time, or any non-negative integer, return a time structure corresponding to the local time zone.

          localtime (time ())
               => {
                     usec = 0
                     sec = 6
                     min = 15
                     hour = 1
                     mday = 17
                     mon = 1
                     year = 97
                     wday = 1
                     yday = 47
                     isdst = 0
                     gmtoff = -21600
                     zone = CST
                  }

     strftime, strptime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday

 -- SECONDS =: mktime (TM_STRUCT)
     Convert a time structure corresponding to the local time to the number of seconds since the epoch.

     For example:

          mktime (localtime (time ()))
               => 856163706

     strftime, strptime, localtime, gmtime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday

 -- STR =: asctime (TM_STRUCT)
     Convert a time structure to a string using the following format: "ddd mmm mm HH:MM:SS yyyy\n".

     For example:

          asctime (localtime (time ()))
               => "Mon Feb 17 01:15:06 1997\n"

     This is equivalent to ctime (time ()). ctime, localtime, time

 -- STR =: strftime (FMT, TM_STRUCT)
     Format the time structure TM_STRUCT in a flexible way using the format string FMT that contains % substitutions similar to those in printf.

     Except where noted, substituted fields have a fixed size; numeric fields are padded if necessary.  Padding is with zeros by default; for fields that display a single number, padding can be changed or inhibited by following the % with one of the modifiers described below.  Unknown field specifiers are copied as normal characters.  All other characters are copied to the output without change.  For example:

          strftime ("%r (%Z) %A %e %B %Y", localtime (time ()))
                => "01:15:06 AM (CST) Monday 17 February 1997"

     Octave's strftime function supports a superset of the ANSI C field specifiers.

     Literal character fields:

     %%
          % character.

     %n
          Newline character.

     %t
          Tab character.

     Numeric modifiers (a nonstandard extension):

     - (dash)
          Do not pad the field.

     _ (underscore)
          Pad the field with spaces.

     Time fields:

     %H
          Hour (00-23).

     %I
          Hour (01-12).

     %k
          Hour (0-23).

     %l
          Hour (1-12).

     %M
          Minute (00-59).

     %p
          Locale's AM or PM.

     %r
          Time, 12-hour (hh:mm:ss [AP]M).

     %R
          Time, 24-hour (hh:mm).

     %s
          Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension).

     %S
          Second (00-61).

     %T
          Time, 24-hour (hh:mm:ss).

     %X
          Locale's time representation (%H:%M:%S).

     %z
          Offset from UTC (±hhmm), or nothing if no time zone is determinable.

     %Z
          Time zone (EDT), or nothing if no time zone is determinable.

     Date fields:

     %a
          Locale's abbreviated weekday name (Sun-Sat).

     %A
          Locale's full weekday name, variable length (Sunday-Saturday).

     %b
          Locale's abbreviated month name (Jan-Dec).

     %B
          Locale's full month name, variable length (January-December).

     %c
          Locale's date and time (Sat Nov 04 12:02:33 EST 1989).

     %C
          Century (00-99).

     %d
          Day of month (01-31).

     %e
          Day of month ( 1-31).

     %D
          Date (mm/dd/yy).

     %h
          Same as %b.

     %j
          Day of year (001-366).

     %m
          Month (01-12).

     %U
          Week number of year with Sunday as first day of week (00-53).

     %w
          Day of week (0-6).

     %W
          Week number of year with Monday as first day of week (00-53).

     %x
          Locale's date representation (mm/dd/yy).

     %y
          Last two digits of year (00-99).

     %Y
          Year (1970-).

     strptime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday

 -- [TM_STRUCT, NCHARS] =: strptime (STR, FMT)
     Convert the string STR to the time structure TM_STRUCT under the control of the format string FMT.

     If FMT fails to match, NCHARS is 0; otherwise, it is set to the position of last matched character plus 1.  Always check for this unless you're absolutely sure the date string will be parsed correctly. strftime, localtime, gmtime, mktime, time, now, date, clock, datenum, datestr, datevec, calendar, weekday

Most of the remaining functions described in this section are not patterned after the standard C library.  Some are available for compatibility with MATLAB and others are provided because they are useful.

 -- DATEVEC =: clock ()
 -- [DATEVEC, ISDST] =: clock ()
     Return the current local date and time as a date vector.

     The date vector contains the following fields: current year, month (1-12), day (1-31), hour (0-23), minute (0-59), and second (0-61).  The seconds field has a fractional part after the decimal point for extended accuracy.

     The optional second output ISDST is true if Daylight Savings Time (DST) is in effect for the system's time zone.

     For example:

          fix (clock ())
            =>   1993      8     20      4     56      1

     clock is more accurate on systems that have the gettimeofday function. now, date, datevec

 -- STR =: date ()
     Return the current date as a character string in the form DD-MMM-YYYY.

     For example:

          date ()
            => 20-Aug-1993

     now, clock, datestr, localtime

 -- SECS =: etime (T2, T1)
     Return the difference in seconds between two time values returned from clock (T2 - T1).

     For example:

          t0 = clock ();
          # many computations later...
          elapsed_time = etime (clock (), t0);

     will set the variable elapsed_time to the number of seconds since the variable t0 was set. tic, toc, clock, cputime, addtodate

 -- [TOTAL, USER, SYSTEM] =: cputime ();
     Return the CPU time used by your Octave session.

     The first output is the total time spent executing your process and is equal to the sum of second and third outputs, which are the number of CPU seconds spent executing in user mode and the number of CPU seconds spent executing in system mode, respectively.

     If your system does not have a way to report CPU time usage, cputime returns 0 for each of its output values.

     Note that because Octave used some CPU time to start, it is reasonable to check to see if cputime works by checking to see if the total CPU time used is nonzero. tic, toc

 -- TF =: is_leap_year ()
 -- TF =: is_leap_year (YEAR)
     Return true if YEAR is a leap year and false otherwise.

     If no year is specified, is_leap_year uses the current year.

     For example:

          is_leap_year (2000)
             => 1

     weekday, eomday, calendar

 -- tic: ()
 -- ID =: tic ()
     Initialize a wall-clock timer.

     Calling tic without an output argument resets the internal timer. Subsequent calls to toc return the number of seconds since the timer was set.

     If called with one output argument, tic creates a new timer instance and returns a timer identifier ID.  The ID is a scalar of type uint64 that may be passed to toc to check elapsed time on this timer, rather than the default internal timer.

     Example 1 : benchmarking code with internal timer

          tic;
          # many computations later...
          elapsed_time = toc;

     Example 2 : mixed timer id and internal timer

          tic;
          pause (1);
          toc
          => Elapsed time is 1.0089 seconds.
          id = tic;
          pause (2);
          toc (id)
          => Elapsed time is 2.01142 seconds.
          toc
          Elapsed time is 3.02308 seconds.

     Calling tic and toc in this way allows nested timing calls.

     If you are more interested in the CPU time that your process used, you should use the cputime function instead.  The tic and toc functions report the actual wall clock time that elapsed between the calls. This may include time spent processing other jobs or doing nothing at all. toc, cputime

 -- toc: ()
 -- toc: (ID)
 -- ELAPSED_TIME =: toc (...)
     Measure elapsed time on a wall-clock timer.

     With no arguments, return the number of seconds elapsed on the internal timer since the last call to tic.

     When given the identifier ID of a specific timer, return the number of seconds elapsed since the timer ID was initialized.

     See tic, for examples of the use of tic/toc.

     tic, cputime

 -- pause: ()
 -- pause: (N)
 -- OLD_STATE =: pause ("on")
 -- OLD_STATE =: pause ("off")
 -- OLD_STATE =: pause ("query")
     Suspend the execution of the program or change the state of the pause function.

     If invoked without an input arguments then the program is suspended until a character is typed.  If argument N is a positive real value, it indicates the number of seconds the program shall be suspended, for example:

          tic; pause (0.05); toc
               -| Elapsed time is 0.05039 seconds.

     The following example prints a message and then waits 5 seconds before clearing the screen.

          disp ("wait please...");
          pause (5);
          clc;

     If invoked with a string argument "on", "off", or "query", the state of the pause function is changed or queried.  When the state is "off", the pause function returns immediately.  The optional return value contains the previous state of the pause function.  In the following example pause is disabled locally:

          old_state = pause ("off");
          tic; pause (0.05); toc
               -| Elapsed time is 3.00407e-05 seconds.
          pause (old_state);

     While the program is suspended Octave still handles figures painting and graphics callbacks execution.

     kbhit

 -- DAYS =: datenum (DATEVEC)
 -- DAYS =: datenum (YEAR, MONTH, DAY)
 -- DAYS =: datenum (YEAR, MONTH, DAY, HOUR)
 -- DAYS =: datenum (YEAR, MONTH, DAY, HOUR, MINUTE)
 -- DAYS =: datenum (YEAR, MONTH, DAY, HOUR, MINUTE, SECOND)
 -- DAYS =: datenum ("datestr")
 -- DAYS =: datenum ("datestr", F)
 -- DAYS =: datenum ("datestr", P)
 -- [DAYS, SECS] =: datenum (...)
     Return the date/time input as a serial day number, with Jan 1, 0000 defined as day 1.

     The integer part, floor (DAYS) counts the number of complete days in the date input.

     The fractional part, rem (DAYS, 1) corresponds to the time on the given day.

     The input may be a date vector (see datevec), date string (see datestr), or directly specified as input.

     When processing input datestrings, F is the format string used to interpret date strings (see datestr).  If no format F is specified, then a relatively slow search is performed through various formats.  It is always preferable to specify the format string F if it is known.  Formats which do not specify a particular time component will have the value set to zero.  Formats which do not specify a date will default to January 1st of the current year.

     When passing separate YEAR, MONTH, DAY, etc. arguments, each may be a scalar or nonscalar array.  Nonscalar inputs must all be of the same size.  Scalar inputs will be expanded to be the size of the nonscalar inputs.

     P is the year at the start of the century to which two-digit years will be referenced.  If not specified, it defaults to the current year minus 50.

     The optional output SECS holds the time on the specified day with greater precision than DAYS.

     Notes:

       * Years can be negative and/or fractional.

       * Months below 1 are considered to be January.

       * Days of the month start at 1.

       * Days beyond the end of the month go into subsequent months.

       * Days before the beginning of the month go to the previous month.

       * Days can be fractional.

     Examples:

          Convert from datestrs:
          d = datenum ("1966-06-14")
          => d = 718232

          d = datenum ({"1966-06-14", "1966-06-15", "1966-06-16"})
          => d =
                718232
                718233
                718234

          Convert from datevec:
          d = datenum ([1966 06 14])
          => d = 718232

          d = datenum ([1966 06 14 23 59 59])
          => d = 718232.9999884259

          Specify date components separately:
          d = datenum (1966, 6, 14)
          => d = 718232

          d = datenum (1966, magic(3), 1)
          => d =

                718280   718068   718219
                718127   718188   718249
                718158   718311   718099

     Caution: datenums represent a specific time for the Earth as a whole.  They do not take in to account time zones (shifts in time based on location), nor seasonal changes due to Daylight Savings Time (shifts in time based on local regulation).  Be aware that it is possible to create datenums that, when interpreted by a function which accounts for time zone and DST shifts such as datestr, are nonexistent or ambiguous.

     Caution: this function does not attempt to handle Julian calendars so dates before October 15, 1582 are wrong by as much as eleven days.  Also, be aware that only Roman Catholic countries adopted the calendar in 1582. It took until 1924 for it to be adopted everywhere.  See the Wikipedia entry on the Gregorian calendar for more details.

     Warning: leap seconds are ignored.  A table of leap seconds is available on the Wikipedia entry for leap seconds.

     datestr, datevec, now, clock, date

 -- STR =: datestr (DATE)
 -- STR =: datestr (DATE, F)
 -- STR =: datestr (DATE, F, P)
     Format the given date/time according to the format F and return the result in STR.

     DATE is a serial date number (see datenum), a date vector (see datevec), or a string or cell array of strings.  In the latter case, it is passed to datevec to guess the input date format.

     F can be an integer which corresponds to one of the codes in the table below, or a date format string.

     P is the year at the start of the century in which two-digit years are to be interpreted in.  If not specified, it defaults to the current year minus 50.

     For example, the date 730736.65149 (2000-09-07 15:38:09.0934) would be formatted as follows:

     Code   Format   Example
     0   dd-mmm-yyyy HH:MM:SS      07-Sep-2000 15:38:09
     1   dd-mmm-yyyy               07-Sep-2000
     2   mm/dd/yy                  09/07/00
     3   mmm                       Sep
     4   m                         S
     5   mm                        09
     6   mm/dd                     09/07
     7   dd                        07
     8   ddd                       Thu
     9   d                         T
     10   yyyy                     2000
     11   yy                       00
     12   mmmyy                    Sep00
     13   HH:MM:SS                 15:38:09
     14   HH:MM:SS PM               3:38:09 PM
     15   HH:MM                    15:38
     16   HH:MM PM                  3:38 PM
     17   QQ-YY                    Q3-00
     18   QQ                       Q3
     19   dd/mm                    07/09
     20   dd/mm/yy                 07/09/00
     21   mmm.dd,yyyy HH:MM:SS     Sep.07,2000 15:38:08
     22   mmm.dd,yyyy              Sep.07,2000
     23   mm/dd/yyyy               09/07/2000
     24   dd/mm/yyyy               07/09/2000
     25   yy/mm/dd                 00/09/07
     26   yyyy/mm/dd               2000/09/07
     27   QQ-YYYY                  Q3-2000
     28   mmmyyyy                  Sep2000
     29   yyyy-mm-dd               2000-09-07
     30   yyyymmddTHHMMSS          20000907T153808
     31   yyyy-mm-dd HH:MM:SS      2000-09-07 15:38:08

     If F is a format string, the following symbols are recognized:

     Symbol   Meaning   Example
     yyyy   Full year                                      2005
     yy     Two-digit year                                 05
     mmmm   Full month name                                December
     mmm    Abbreviated month name                         Dec
     mm     Numeric month number (padded with zeros)       01, 08, 12
     m      First letter of month name (capitalized)       D
     dddd   Full weekday name                              Sunday
     ddd    Abbreviated weekday name                       Sun
     dd     Numeric day of month (padded with zeros)       11
     d      First letter of weekday name (capitalized)     S
     HH     Hour of day, padded with zeros,                09:00
       or padded with spaces if PM is set              9:00 AM
     MM     Minute of hour (padded with zeros)             10:05
     SS     Second of minute (padded with zeros)           10:05:03
     FFF    Milliseconds of second (padded with zeros)     10:05:03.012
     AM     Use 12-hour time format                        11:30 AM
     PM     Use 12-hour time format                        11:30 PM

     If F is not specified or is -1, then use 0, 1 or 16, depending on whether the date portion or the time portion of DATE is empty.

     If P is not specified, it defaults to the current year minus 50.

     If a matrix or cell array of dates is given, a column vector of date strings is returned.

     datenum, datevec, date, now, clock

 -- V =: datevec (DATE)
 -- V =: datevec (DATE, F)
 -- V =: datevec (DATE, P)
 -- V =: datevec (DATE, F, P)
 -- [Y, M, D, H, MI, S] =: datevec (...)
     Convert a serial date number (see datenum) or date string (see datestr) into a date vector.

     A date vector is a row vector with six members, representing the year, month, day, hour, minute, and seconds respectively.

     Date number inputs can be either a scalar or nonscalar array.  Date string inputs can be either a single date string, a two-dimensional character array of dates with each row being a date string, or a cell string array of any dimension with each cell element containing a single date string.

     V is a two-dimensional array of date vectors, one date vector per row.  For array inputs, ordering of V is based on column major order of dates in DATA.

     F is the format string used to interpret date strings (see datestr).  If DATE is a string or a cell array of strings, but no format is specified, heuristics are used to guess the input format.  These heuristics could lead to matches that differ from the result a user might expect.  Additionally, this involves a relatively slow search through various formats.  It is always preferable to specify the format string F if it is known.  Formats which do not specify a particular time component will have the value set to zero.  Formats which do not specify a particular date component will default that component to January 1st of the current year.  Trailing characters are ignored for the purpose of calculating the date vector, even if the characters contain additional time/date information.

     P is the year at the start of the century to which two-digit years will be referenced.  If not specified, it defaults to the current year minus 50. datenum, datestr, clock, now, date

 -- D =: addtodate (D, Q, F)
     Add Q amount of time (with units F) to the serial datenum, D.

     F must be one of "year", "month", "day", "hour", "minute", "second", or "millisecond". datenum, datevec, etime

 -- C =: calendar ()
 -- C =: calendar (D)
 -- C =: calendar (Y, M)
 -- calendar: (...)
     Return the current monthly calendar in a 6x7 matrix.

     If D is specified, return the calendar for the month containing the date D, which must be a serial date number or a date string.

     If Y and M are specified, return the calendar for year Y and month M.

     If no output arguments are specified, print the calendar on the screen instead of returning a matrix. datenum, datestr

 -- [N, S] =: weekday (D)
 -- [N, S] =: weekday (D, FORMAT)
     Return the day of the week as a number in N and as a string in S.

     The days of the week are numbered 1--7 with the first day being Sunday.

     D is a serial date number or a date string.

     If the string FORMAT is not present or is equal to "short" then S will contain the abbreviated name of the weekday.  If FORMAT is "long" then S will contain the full name.

     Table of return values based on FORMAT:

     N   "short"   "long"
     1   Sun   Sunday
     2   Mon   Monday
     3   Tue   Tuesday
     4   Wed   Wednesday
     5   Thu   Thursday
     6   Fri   Friday
     7   Sat   Saturday

     eomday, is_leap_year, calendar, datenum, datevec

 -- E =: eomday (Y, M)
     Return the last day of the month M for the year Y. weekday, datenum, datevec, is_leap_year, calendar

 -- datetick: ()
 -- datetick: (AXIS_STR)
 -- datetick: (DATE_FORMAT)
 -- datetick: (AXIS_STR, DATE_FORMAT)
 -- datetick: (..., "keeplimits")
 -- datetick: (..., "keepticks")
 -- datetick: (HAX, ...)
     Add date-formatted tick labels to an axis.

     The axis to apply the ticks to is determined by AXIS_STR which can take the values "x", "y", or "z".  The default value is "x".

     The formatting of the labels is determined by the variable DATE_FORMAT, which can either be a string or positive integer that datestr accepts.

     If the first argument HAX is an axes handle, then plot into this axes, rather than the current axes returned by gca.

     datenum, datestr

Filesystem Utilities
====================

Octave includes many utility functions for copying, moving, renaming, and deleting files; for creating, reading, and deleting directories; for retrieving status information on files; and for manipulating file and path names.

 -- movefile: F1
 -- movefile: F1 F2
 -- movefile: F1 F2 f
 -- movefile: (F1)
 -- movefile: (F1, F2)
 -- movefile: (F1, F2, 'f')
 -- [STATUS] =: movefile (...)
 -- [STATUS, MSG] =: movefile (...)
 -- [STATUS, MSG, MSGID] =: movefile (...)
     Move the source file or directory F1 to the destination F2.

     The name F1 may contain globbing patterns, or may be a cell array of strings.  If F1 expands to multiple filenames, F2 must be a directory.

     If no destination F2 is specified then the destination is the present working directory.  If F2 is a filename then F1 is renamed to F2.

     When the force flag 'f' is given any existing files will be overwritten without prompting.

     If successful, STATUS is logical 1, and MSG, MSGID are empty character strings ("").  Otherwise, STATUS is logical 0, MSG contains a system-dependent error message, and MSGID contains a unique message identifier.  Note that the status code is exactly opposite that of the system command. rename, copyfile, unlink, delete, glob

 -- rename: OLD NEW
 -- [STATUS, MSG] =: rename (OLD, NEW)
     Change the name of file OLD to NEW.

     If successful, STATUS is 0 and MSG is an empty string. Otherwise, STATUS is -1 and MSG contains a system-dependent error message. movefile, copyfile, ls, dir

 -- copyfile: F1 F2
 -- copyfile: F1 F2 f
 -- copyfile: (F1, F2)
 -- copyfile: (F1, F2, 'f')
 -- [STATUS, MSG, MSGID] =: copyfile (...)
     Copy the source file(s) or directory F1 to the destination F2.

     The name F1 may contain globbing patterns, or may be a cell array of strings.  If F1 expands to multiple filenames, F2 must be a directory.

     When the force flag 'f' is given any existing files will be overwritten without prompting.

     If successful, STATUS is logical 1, and MSG, MSGID are empty character strings ("").  Otherwise, STATUS is logical 0, MSG contains a system-dependent error message, and MSGID contains a unique message identifier.  Note that the status code is exactly opposite that of the system command. movefile, rename, unlink, delete, glob

 -- unlink: (FILE)
 -- [STATUS, MSG] =: unlink (FILE)
     Delete the file named FILE.

     If successful, STATUS is 0 and MSG is an empty string. Otherwise, STATUS is -1 and MSG contains a system-dependent error message. delete, rmdir

 -- link: OLD NEW
 -- [STATUS, MSG] =: link (OLD, NEW)
     Create a new link (also known as a hard link) to an existing file.

     If successful, STATUS is 0 and MSG is an empty string. Otherwise, STATUS is -1 and MSG contains a system-dependent error message. symlink, unlink, readlink, lstat

 -- symlink: OLD NEW
 -- [STATUS, MSG] =: symlink (OLD, NEW)
     Create a symbolic link NEW which contains the string OLD.

     If successful, STATUS is 0 and MSG is an empty string. Otherwise, STATUS is -1 and MSG contains a system-dependent error message. link, unlink, readlink, lstat

 -- RESULT =: readlink SYMLINK
 -- [RESULT, ERR, MSG] =: readlink (SYMLINK)
     Read the value of the symbolic link SYMLINK.

     If successful, RESULT contains the contents of the symbolic link SYMLINK, ERR is 0, and MSG is an empty string. Otherwise, ERR is nonzero and MSG contains a system-dependent error message. lstat, symlink, link, unlink, delete

 -- mkdir: DIRNAME
 -- mkdir: PARENT DIRNAME
 -- mkdir: (DIRNAME)
 -- mkdir: (PARENT, DIRNAME)
 -- [STATUS, MSG, MSGID] =: mkdir (...)
     Create a directory named DIRNAME in the directory PARENT, creating any intermediate directories if necessary.

     If DIRNAME is a relative path, and no PARENT directory is specified, then the present working directory is used.

     If successful, STATUS is logical 1, and MSG, MSGID are empty character strings ("").  Otherwise, STATUS is logical 0, MSG contains a system-dependent error message, and MSGID contains a unique message identifier.  Note that the status code is exactly opposite that of the system command.

     When creating a directory permissions will be set to 0777 - UMASK.

     rmdir, pwd, cd, umask

 -- rmdir: DIR
 -- rmdir: (DIR, "s")
 -- [STATUS, MSG, MSGID] =: rmdir (...)
     Remove the directory named DIR.

     If the optional second parameter is supplied with value "s", recursively remove all subdirectories as well.

     If successful, STATUS is logical 1, and MSG, MSGID are empty character strings ("").  Otherwise, STATUS is logical 0, MSG contains a system-dependent error message, and MSGID contains a unique message identifier.

     mkdir, confirm_recursive_rmdir, pwd

 -- VAL =: confirm_recursive_rmdir ()
 -- OLD_VAL =: confirm_recursive_rmdir (NEW_VAL)
 -- OLD_VAL =: confirm_recursive_rmdir (NEW_VAL, "local")
     Query or set the internal variable that controls whether Octave will ask for confirmation before recursively removing a directory tree.

     When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function. rmdir

 -- mkfifo: (NAME, MODE)
 -- [STATUS, MSG] =: mkfifo (NAME, MODE)
     Create a FIFO special file named NAME with file mode MODE.

     MODE is interpreted as an octal number and is subject to umask processing.  The final calculated mode is MODE - UMASK.

     If successful, STATUS is 0 and MSG is an empty string. Otherwise, STATUS is -1 and MSG contains a system-dependent error message. pipe, umask

 -- OLDMASK =: umask (MASK)
     Set the permission mask for file creation.

     The parameter MASK is an integer, interpreted as an octal number.

     If successful, returns the previous value of the mask (as an integer to be interpreted as an octal number); otherwise an error message is printed.

     The permission mask is a UNIX concept used when creating new objects on a file system such as files, directories, or named FIFOs.  The object to be created has base permissions in an octal number MODE which are modified according to the octal value of MASK.  The final permissions for the new object are MODE - MASK. fopen, mkdir, mkfifo

 -- [INFO, ERR, MSG] =: stat (FILE)
 -- [INFO, ERR, MSG] =: stat (FID)
 -- [INFO, ERR, MSG] =: lstat (FILE)
 -- [INFO, ERR, MSG] =: lstat (FID)
     Return a structure INFO containing the following information about FILE or file identifier FID.

     dev
          ID of device containing a directory entry for this file.

     ino
          File number of the file.

     mode
          File mode, as an integer.  Use the functions S_ISREG, S_ISDIR, S_ISCHR, S_ISBLK, S_ISFIFO, S_ISLNK, or S_ISSOCK to extract information from this value.

     modestr
          File mode, as a string of ten letters or dashes as would be returned by ls -l.

     nlink
          Number of links.

     uid
          User ID of file's owner.

     gid
          Group ID of file's group.

     rdev
          ID of device for block or character special files.

     size
          Size in bytes.

     atime
          Time of last access in the same form as time values returned from time.  See Timing Utilities.

     mtime
          Time of last modification in the same form as time values returned from time.  See Timing Utilities.

     ctime
          Time of last file status change in the same form as time values returned from time.  See Timing Utilities.

     blksize
          Size of blocks in the file.

     blocks
          Number of blocks allocated for file.

     If the call is successful ERR is 0 and MSG is an empty string. If the file does not exist, or some other error occurs, INFO is an empty matrix, ERR is -1, and MSG contains the corresponding system error message.

     If FILE is a symbolic link, stat will return information about the actual file that is referenced by the link.  Use lstat if you want information about the symbolic link itself.

     For example:

          [info, err, msg] = stat ("/vmlinuz")
            => info =
               {
                 atime = 855399756
                 rdev = 0
                 ctime = 847219094
                 uid = 0
                 size = 389218
                 blksize = 4096
                 mtime = 847219094
                 gid = 6
                 nlink = 1
                 blocks = 768
                 mode = -rw-r--r--
                 modestr = -rw-r--r--
                 ino = 9316
                 dev = 2049
               }
            => err = 0
            => msg =

     lstat, ls, dir, isfile, isfolder

 -- TF =: S_ISBLK (MODE)
     Return true if MODE corresponds to a block device.

     The value of MODE is assumed to be returned from a call to stat. stat, lstat

 -- TF =: S_ISCHR (MODE)
     Return true if MODE corresponds to a character device.

     The value of MODE is assumed to be returned from a call to stat. stat, lstat

 -- TF =: S_ISDIR (MODE)
     Return true if MODE corresponds to a directory.

     The value of MODE is assumed to be returned from a call to stat. stat, lstat

 -- TF =: S_ISFIFO (MODE)
     Return true if MODE corresponds to a fifo.

     The value of MODE is assumed to be returned from a call to stat. stat, lstat

 -- TF =: S_ISLNK (MODE)
     Return true if MODE corresponds to a symbolic link.

     The value of MODE is assumed to be returned from a call to stat. stat, lstat

 -- TF =: S_ISREG (MODE)
     Return true if MODE corresponds to a regular file.

     The value of MODE is assumed to be returned from a call to stat. stat, lstat

 -- TF =: S_ISSOCK (MODE)
     Return true if MODE corresponds to a socket.

     The value of MODE is assumed to be returned from a call to stat. stat, lstat

 -- fileattrib:
 -- fileattrib: FILE
 -- fileattrib: (FILE)
 -- [STATUS, ATTRIB] =: fileattrib (...)
 -- [STATUS, MSG, MSGID] =: fileattrib (...)
     Report attribute information about FILE.

     If no file or directory is specified, report information about the present working directory.

     If successful, the output is a structure with the following fields:

     Name
          Full name of FILE.

     archive
          True if FILE is an archive (Windows).

     system
          True if FILE is a system file (Windows).

     hidden
          True if FILE is a hidden file (Windows).

     directory
          True if FILE is a directory.

     UserRead
     GroupRead
     OtherRead
          True if the user (group; other users) has read permission for FILE.

     UserWrite
     GroupWrite
     OtherWrite
          True if the user (group; other users) has write permission for FILE.

     UserExecute
     GroupExecute
     OtherExecute
          True if the user (group; other users) has execute permission for FILE.

     If an attribute does not apply (e.g., archive on a Unix system) then the field is set to NaN.

     If FILE contains globbing characters, information about all matching files is returned in a structure array.

     If outputs are requested, the first is STATUS which takes the value 1 when the operation was successful, and 0 otherwise.  The second output contains the structure described above (ATTRIB) if the operation was successful; otherwise, the second output is a system-dependent error message (MSG).  The third output is an empty string ("") when the operation was successful, or a unique message identifier (MSGID) in the case of failure. stat, glob

 -- TF =: isfile (F)
     Return true if F is a regular file and false otherwise.

     If F is a cell array of strings, TF is a logical array of the same size. isfolder, exist, stat, is_absolute_filename, is_rooted_relative_filename

 -- TF =: isdir (F)

     This function is not recommended.  Use isfolder or file_in_loadpath instead.

     Return true if F is a directory and false otherwise.

     Compatibility Note: The MATLAB function of the same name will also search for F in the load path directories.  To emulate this behavior use

          TF = ! isempty (file_in_loadpath (F))

     isfolder, file_in_loadpath, exist, stat, is_absolute_filename, is_rooted_relative_filename

 -- TF =: isfolder (F)
     Return true if F is a directory and false otherwise.

     If F is a cell array of strings, TF is a logical array of the same size. isfile, exist, stat, is_absolute_filename, is_rooted_relative_filename

 -- FILES =: readdir (DIR)
 -- [FILES, ERR, MSG] =: readdir (DIR)
     Return the names of files in the directory DIR as a cell array of strings.

     If an error occurs, return an empty cell array in FILES. If successful, ERR is 0 and MSG is an empty string. Otherwise, ERR is nonzero and MSG contains a system-dependent error message. ls, dir, glob, what

 -- CSTR =: glob (PATTERN)
     Given an array of pattern strings (as a char array or a cell array) in PATTERN, return a cell array of filenames that match any of them, or an empty cell array if no patterns match.

     The pattern strings are interpreted as filename globbing patterns (as they are used by Unix shells).

     Within a pattern

     *
          matches any string, including the null string,

     ?
          matches any single character, and

     [...]
          matches any of the enclosed characters.

     Tilde expansion is performed on each of the patterns before looking for matching filenames.  For example:

          ls
             =>
                file1  file2  file3  myfile1 myfile1b
          glob ("*file1")
             =>
                {
                  [1,1] = file1
                  [2,1] = myfile1
                }
          glob ("myfile?")
             =>
                {
                  [1,1] = myfile1
                }
          glob ("file[12]")
             =>
                {
                  [1,1] = file1
                  [2,1] = file2
                }

     Note: On Windows, patterns that contain non-ASCII characters are not supported.

     ls, dir, readdir, what

 -- FNAME =: file_in_path (PATH, FILE)
 -- FNAME =: file_in_path (PATH, FILE, "all")
     Return the absolute name of FILE if it can be found in PATH.

     The value of PATH should be a colon-separated list of directories in the format described for path.  If no file is found, return an empty character string.  For example:

          file_in_path (EXEC_PATH, "sh")
               => "/bin/sh"

     If the second argument is a cell array of strings, search each directory of the path for element of the cell array and return the first that matches.

     If the third optional argument "all" is supplied, return a cell array containing the list of all files that have the same name in the path. If no files are found, return an empty cell array. file_in_loadpath, dir_in_loadpath, path

 -- SEP =: filesep ()
 -- filesep: ("all")
     Return the system-dependent character used to separate directory names.

     If "all" is given, the function returns all valid file separators in the form of a string.  The list of file separators is system-dependent. It is / (forward slash) under UNIX or Mac OS X, / and \ (forward and backward slashes) under Windows. pathsep

 -- [DIR, NAME, EXT] =: fileparts (FILENAME)
     Return the directory, name, and extension components of FILENAME.

     The input FILENAME is a string which is parsed.  There is no attempt to check whether the filename or directory specified actually exists. fullfile, filesep

 -- FILENAME =: fullfile (DIR1, DIR2, ..., FILE)
     Build complete filename from separate parts.

     The function joins any number of path components intelligently.  The return value is the concatenation of each component with exactly one file separator between each part of the path and at most one leading and/or trailing file separator.

     The input arguments might be strings or cell strings.  Any input arguments that are cell strings must contain one single string or must be equal in size.  In that case, the function returns a cell string of filepaths of the same dimensions as the input cell strings, e.g.:

          fullfile ("/home/username", "data", {"f1.csv", "f2.csv", "f3.csv"})
            =>
                {
                  [1,1] = /home/username/data/f1.csv
                  [1,2] = /home/username/data/f2.csv
                  [1,3] = /home/username/data/f3.csv
                }

     On Windows systems, while forward slash file separators do work, they are replaced by backslashes.  In addition, drive letters are stripped of leading file separators to obtain a valid file path.

     Note: fullfile does not perform any validation of the resulting full filename. fileparts, filesep

 -- NEWSTR =: tilde_expand (STRING)
 -- NEWCSTR =: tilde_expand (CELLSTR)
     Perform tilde expansion on STRING.

     If STRING begins with a tilde character, (~), 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.

     If the input is a cell array of strings CELLSTR then tilde expansion is performed on each string element.

     Examples:

          tilde_expand ("~joeuser/bin")
               => "/home/joeuser/bin"
          tilde_expand ("~/bin")
               => "/home/jwe/bin"

 -- [CNAME, STATUS, MSG] =: canonicalize_file_name (FNAME)
     Return the canonical name of file FNAME.

     If the file does not exist the empty string ("") is returned.  No tilde expansion of FNAME is performed. make_absolute_filename, is_absolute_filename, is_rooted_relative_filename, is_same_file, tilde_expand

 -- ABS_FNAME =: make_absolute_filename (FILE)
     Return the full name of FILE beginning from the root of the file system.

     No check is done for the existence of FILE.  No tilde expansion of FILE is performed. canonicalize_file_name, is_absolute_filename, is_rooted_relative_filename, isfolder, tilde_expand

 -- TF =: is_absolute_filename (FILE)
     Return true if FILE is an absolute filename. is_rooted_relative_filename, make_absolute_filename, isfolder

 -- SAME =: is_same_file (FILEPATH1, FILEPATH2)
     Return true if FILEPATH1 and FILEPATH2 refer to the same file.

     If either FILEPATH1 or FILEPATH2 is a cell array of strings, then an array of the same size is returned, containing the values described above for every member of the cell array.  The other argument may also be a cell array of strings (of the same size) or a string.

     Programming Notes: Depending on the operating system and file system, the same file or folder can be referred to with different paths.  In particular, paths on the Windows platform may differ in case (file1 vs. FILE1), file separator (\ vs. /), and format (A~spaces.txt (8.3 convention) vs. A filename with spaces.txt).  This function returns true if the paths in FILEPATH1 and FILEPATH2 actually refer to the same file or folder, and false otherwise.

     Note that unlike strcmp, this function requires that FILEPATH1 and FILEPATH2 exist, as well as point to the same location, in order to return true.

     canonicalize_file_name, strcmp

 -- TF =: is_rooted_relative_filename (FILE)
     Return true if FILE is a rooted-relative filename. is_absolute_filename, make_absolute_filename, isfolder

 -- VAL =: recycle ()
 -- OLD_VAL =: recycle (NEW_VAL)
     Query or set the preference for recycling deleted files.

     When recycling is enabled, commands which would permanently erase files instead move them to a temporary location (such as the directory labeled Trash).

     Programming Note: This function is provided for MATLAB compatibility, but recycling is not implemented in Octave.  To help avoid accidental data loss an error will be raised if an attempt is made to enable file recycling. delete, rmdir

File Archiving Utilities
========================

 -- bunzip2: (BZFILE)
 -- bunzip2: (BZFILE, DIR)
 -- FILELIST =: bunzip2 (...)
     Unpack the bzip2 archive BZFILE.

     If DIR is specified the files are unpacked in this directory rather than the one where BZFILE is located.

     The optional output FILELIST is a list of the uncompressed files. bzip2, unpack, gunzip, unzip, untar

 -- FILELIST =: gzip (FILES)
 -- FILELIST =: gzip (FILES, DIR)
     Compress the list of files and directories specified in FILES.

     FILES is a character array or cell array of strings.  Shell wildcards in the filename such as * or ? are accepted and expanded. Each file is compressed separately and a new file with a ".gz" extension is created.  The original files are not modified, but existing compressed files will be silently overwritten.  If a directory is specified then gzip recursively compresses all files in the directory.

     If DIR is defined the compressed files are placed in this directory, rather than the original directory where the uncompressed file resides. Note that this does not replicate a directory tree in DIR which may lead to files overwriting each other if there are multiple files with the same name.

     If DIR does not exist it is created.

     The optional output FILELIST is a list of the compressed files. gunzip, unpack, bzip2, zip, tar

 -- gunzip: (GZFILE)
 -- gunzip: (GZFILE, OUTDIR)
 -- FILELIST =: gunzip (...)
     Unpack the gzip archive GZFILE.

     If GZFILE is a directory, all gzfiles in the directory will be recursively unpacked.

     If OUTDIR is specified the files are unpacked in this directory rather than the one where GZFILE is located.

     The optional output FILELIST is a list of the uncompressed files. gzip, unpack, bunzip2, unzip, untar

 -- FILELIST =: tar (TARFILE, FILES)
 -- FILELIST =: tar (TARFILE, FILES, ROOTDIR)
     Pack the list of files and directories specified in FILES into the TAR archive TARFILE.

     FILES is a character array or cell array of strings.  Shell wildcards in the filename such as * or ? are accepted and expanded. Directories are recursively traversed and all files are added to the archive.

     If ROOTDIR is defined then any files without absolute pathnames are located relative to ROOTDIR rather than the current directory.

     The optional output FILELIST is a list of the files that were included in the archive. untar, unpack, bzip2, gzip, zip

 -- untar: (TARFILE)
 -- untar: (TARFILE, DIR)
 -- FILELIST =: untar (...)
     Unpack the TAR archive TARFILE.

     If DIR is specified the files are unpacked in this directory rather than the current directory.

     The optional output FILELIST is a list of the uncompressed files. tar, unpack, bunzip2, gunzip, unzip

 -- FILELIST =: zip (ZIPFILE, FILES)
 -- FILELIST =: zip (ZIPFILE, FILES, ROOTDIR)
     Compress the list of files and directories specified in FILES into the ZIP archive ZIPFILE.

     FILES is a character array or cell array of strings.  Shell wildcards in the filename such as * or ? are accepted and expanded.  Directories are recursively traversed and all files are compressed and added to the archive.

     If ROOTDIR is defined then any files without absolute pathnames are located relative to ROOTDIR rather than the current directory.

     The optional output FILELIST is a list of the files that were included in the archive. unzip, unpack, bzip2, gzip, tar

 -- unzip: (ZIPFILE)
 -- unzip: (ZIPFILE, DIR)
 -- FILELIST =: unzip (...)
     Unpack the ZIP archive ZIPFILE.

     If DIR is specified the files are unpacked in this directory rather than the current directory.

     The optional output FILELIST is a list of the uncompressed files. zip, unpack, bunzip2, gunzip, untar

 -- FILES =: unpack (FILE)
 -- FILES =: unpack (FILE, DIR)
 -- FILES =: unpack (FILE, DIR, FILETYPE)
     Unpack the archive FILE based on its extension to the directory DIR.

     If FILE is a list of strings, then each file is unpacked individually.  Shell wildcards in the filename such as * or ? are accepted and expanded.

     If DIR is not specified or is empty ([]), it defaults to the current directory.  If a directory is in the file list, then FILETYPE must also be specified.

     The specific archive filetype is inferred from the extension of the file. The FILETYPE may also be specified directly using a string which corresponds to a known extension.

     Valid filetype extensions:

     bz
     bz2
          bzip archive

     gz
          gzip archive

     tar
          tar archive

     tarbz
     tarbz2
     tbz
     tbz2
          tar + bzip archive

     targz
     tgz
          tar + gzip archive

     z
          compress archive

     zip
          zip archive

     The optional return value is a list of FILES unpacked. bunzip2, gunzip, unzip, untar, bzip2, gzip, zip, tar

 -- FILELIST =: bzip2 (FILES)
 -- FILELIST =: bzip2 (FILES, DIR)
     Compress the list of files specified in FILES.

     FILES is a character array or cell array of strings.  Shell wildcards in the filename such as * or ? are accepted and expanded. Each file is compressed separately and a new file with a ".bz2" extension is created.  The original files are not modified, but existing compressed files will be silently overwritten.

     If DIR is defined the compressed files are placed in this directory, rather than the original directory where the uncompressed file resides. Note that this does not replicate a directory tree in DIR which may lead to files overwriting each other if there are multiple files with the same name.

     If DIR does not exist it is created.

     The optional output FILELIST is a list of the compressed files. bunzip2, unpack, gzip, zip, tar

Networking Utilities
====================

 -- NAME =: gethostname ()
     Return the hostname of the system where Octave is running.

FTP Objects
-----------

Octave supports the FTP protocol through an object-oriented interface. Use the function ftp to create an FTP object which represents the connection.  All FTP functions take an FTP object as the first argument.

 -- F =: ftp (HOST)
 -- F =: ftp (HOST, USERNAME, PASSWORD)
     Connect to the FTP server HOST with USERNAME and PASSWORD.

     If USERNAME and PASSWORD are not specified, user "anonymous" with no password is used.  The returned FTP object F represents the established FTP connection.

     The list of actions for an FTP object are shown below.  All functions require an FTP object as the first argument.

     Method   Description
     ascii   Set transfer type to ascii
     binary   Set transfer type to binary
     cd   Change remote working directory
     close   Close FTP connection
     delete   Delete remote file
     dir   List remote directory contents
     mget   Download remote files
     mkdir   Create remote directory
     mput   Upload local files
     rename   Rename remote file or directory
     rmdir   Remove remote directory

     @ftp/ascii, @ftp/binary, @ftp/cd, @ftp/close, @ftp/delete, @ftp/dir, @ftp/mget, @ftp/mkdir, @ftp/mput, @ftp/rename, @ftp/rmdir

 -- close: (F)
     Close the FTP connection represented by the FTP object F.

     F is an FTP object returned by the ftp function. @ftp/ftp

 -- mget: (F, FILE)
 -- mget: (F, DIR)
 -- mget: (F, REMOTE_NAME, TARGET)
     Download a remote file FILE or directory DIR to the local directory on the FTP connection F.

     F is an FTP object returned by the ftp function.

     The arguments FILE and DIR can include wildcards and any files or directories on the remote server that match will be downloaded.

     If a third string argument TARGET is given, then it must indicate the path to the local destination directory.  TARGET may be a relative or absolute path. @ftp/mput, @ftp/ftp

 -- mput: (F, FILE)
 -- FILE_LIST =: mput (F, FILE)
     Upload the local file FILE into the current remote directory on the FTP connection F.

     F is an FTP object returned by the ftp function.

     The argument FILE is passed through the glob function and any files that match the wildcards in FILE will be uploaded.

     The optional output argument FILE_LIST contains a cell array of strings with the names of the uploaded files. @ftp/mget, @ftp/mkdir, @ftp/ftp

 -- CWD =: cd (F)
 -- cd: (F, PATH)
 -- NEW_CWD =: cd (F, PATH)
     Get or set the remote directory on the FTP connection F.

     F is an FTP object returned by the ftp function.

     If PATH is not specified, return the remote current working directory.  Otherwise, set the remote directory to PATH and return the new remote working directory.

     If the directory does not exist, an error message is printed and the working directory is not changed. @ftp/dir, @ftp/ftp

 -- dir: (F)
 -- LST =: dir (F)
     List the current directory in verbose form for the FTP connection F.

     F is an FTP object returned by the ftp function.

     If the optional output LST is requested return a struct array with one entry per file with the fields name, date, bytes, isdir, datenum. @ftp/cd, @ftp/mkdir, @ftp/rmdir, @ftp/ftp

 -- ascii: (F)
     Set the FTP connection F to use ASCII mode for transfers.

     ASCII mode is only appropriate for text files as it will convert the remote host's newline representation to the local host's newline representation.

     F is an FTP object returned by the ftp function. @ftp/binary, @ftp/ftp

 -- binary: (F)
     Set the FTP connection F to use binary mode for transfers.

     In binary mode there is no conversion of newlines from the remote representation to the local representation.

     F is an FTP object returned by the ftp function. @ftp/ascii, @ftp/ftp

 -- delete: (F, FILE)
     Delete the remote file FILE over the FTP connection F.

     F is an FTP object returned by the ftp function. @ftp/rmdir, @ftp/rename, @ftp/ftp

 -- rename: (F, OLDNAME, NEWNAME)
     Rename or move the remote file or directory OLDNAME to NEWNAME, over the FTP connection F.

     F is an FTP object returned by the ftp function. @ftp/delete, @ftp/rmdir, @ftp/ftp

 -- mkdir: (F, PATH)
     Create the remote directory PATH, over the FTP connection F.

     F is an FTP object returned by the ftp function. @ftp/rmdir, @ftp/ftp

 -- rmdir: (F, PATH)
     Remove the remote directory PATH, over the FTP connection F.

     F is an FTP object returned by the ftp function. @ftp/delete, @ftp/mkdir, @ftp/rename, @ftp/ftp

WWW Access
----------

Octave can communicate with websites across the Internet.  The web function will launch an external web browser to interactively view a site.  The remaining functions---urlread, urlwrite, webread, webwrite---are internal Octave functions which can import or export data to/from Octave and a website identified by a URL (Uniform Resource Locator).

 -- STATUS =: web ()
 -- STATUS =: web (URL)
 -- STATUS =: web (URL, OPTION)
 -- STATUS =: web (URL, OPTION_1, ..., OPTION_N)
 -- [STATUS, H, URL] =: web (...)

     Open URL in the default system web browser.

     With no arguments given, the address https://www.octave.org is opened.

     Additional options can be passed for MATLAB compatibility, but are ignored.

       * -browser Open URL in the default system browser.

       * -new No effect on the system browser.

       * -noaddressbox No effect on the system browser.

       * -notoolbar No effect on the system browser.

     The return value STATUS has one of the values:

       * 0 Found and opened system browser successfully.

       * 1 Cannot find the system browser.

       * 2 System browser found, but an error occurred.

     The return values HANDLE and URL are currently unimplemented but given for compatibility.

     weboptions, webread, webwrite, urlread, urlwrite

 -- S =: urlread (URL)
 -- [S, SUCCESS] =: urlread (URL)
 -- [S, SUCCESS, MESSAGE] =: urlread (URL)
 -- [...] =: urlread (URL, METHOD, PARAM)
     Download a remote file specified by its URL and return its content in string S.

     For example:

          s = urlread ("http://ftp.octave.org/pub/README");

     The variable SUCCESS is 1 if the download was successful, otherwise it is 0 in which case MESSAGE contains an error message.

     If no output argument is specified and an error occurs, then the error is signaled through Octave's error handling mechanism.

     This function uses libcurl.  The curl library supports, among others, the HTTP, FTP, and FILE protocols.  Username and password may be specified in the URL. For example:

          s = urlread ("http://user:password@example.com/file.txt");

     GET and POST requests can be specified by METHOD and PARAM. The parameter METHOD is either get or post and PARAM is a cell array of parameter and value pairs. For example:

          s = urlread ("http://www.google.com/search",
                       "get", {"query", "octave"});

     urlwrite

 -- urlwrite: (URL, LOCALFILE)
 -- F =: urlwrite (URL, LOCALFILE)
 -- [F, SUCCESS] =: urlwrite (URL, LOCALFILE)
 -- [F, SUCCESS, MESSAGE] =: urlwrite (URL, LOCALFILE)
     Download a remote file specified by its URL and save it as LOCALFILE.

     For example:

          urlwrite ("http://ftp.octave.org/pub/README",
                    "README.txt");

     The full path of the downloaded file is returned in F.

     The variable SUCCESS is 1 if the download was successful, otherwise it is 0 in which case MESSAGE contains an error message.

     If no output argument is specified and an error occurs, then the error is signaled through Octave's error handling mechanism.

     This function uses libcurl.  The curl library supports, among others, the HTTP, FTP, and FILE protocols.  Username and password may be specified in the URL, for example:

          urlwrite ("http://username:password@example.com/file.txt",
                    "file.txt");

     GET and POST requests can be specified by METHOD and PARAM. The parameter METHOD is either get or post and PARAM is a cell array of parameter and value pairs. For example:

          urlwrite ("http://www.google.com/search", "search.html",
                    "get", {"query", "octave"});

     urlread

 -- RESPONSE =: webread (URL)
 -- RESPONSE =: webread (URL, NAME1, VALUE1, ...)
 -- RESPONSE =: webread (..., OPTIONS)

     Read content from RESTful web service.

     Read content from the web service specified by URL and return the content in RESPONSE.

     All key-value pairs given (NAME1, VALUE1, ...) are appended as query parameters to URL.  To place a query in the body of the message, use webwrite.  The web service defines the acceptable query parameters.

     OPTIONS is a weboptions object that may be used to add other HTTP request options.  This argument can be used with either calling form. See help weboptions for a complete list of supported HTTP options.

     weboptions, webwrite

 -- RESPONSE =: webwrite (URL, NAME1, VALUE1, ...)
 -- RESPONSE =: webwrite (URL, DATA)
 -- RESPONSE =: webwrite (..., OPTIONS)

     Write data to RESTful web services.

     Write content to the web service specified by URL and return the response in RESPONSE.

     All key-value pairs given (NAME1, VALUE1, ...) are added as pairs of query parameters to the body of request method (get, post, put, etc.).

     OPTIONS is a weboptions object that may be used to add other HTTP request options.  This argument can be used with either calling form. See help weboptions for a complete list of supported HTTP options.

     weboptions, webread

 -- OUTPUT =: weboptions ()
 -- OUTPUT =: weboptions (NAME1, VALUE1, ...)

     Specify parameters for RESTful web services.

     weboptions with no inputs returns a default weboptions object to specify parameters for a request to a web service.  A weboptions object can be an optional input argument to the webread and webwrite functions.

     Multiple name and value pair arguments may be specified in any order as NAME1, VALUE1, NAME2, VALUE2, etc.

     The option names must match exactly one of those specified in the table below.

     The following options are available:

       * CharacterEncoding --- Specify the character encoding of the data:

          auto (default), UTF-8, US-ASCII auto chooses an encoding based on the content-type of the data.

       * UserAgent --- Specify the User Agent for the connection.

          Default value is GNU Octave/version, where version is the current version of Octave as returned by version.

       * Timeout --- Specify the timeout value for the connection in seconds.

          Default is 10 seconds.  Inf is not currently supported.

       * Username --- User identifier for a basic HTTP connection.

          Default is NULL.  It must be a string.

       * Password --- User authentication password for HTTP connection.

          Default is NULL.  It must be a string or character vector. Programming Note: If you display a weboption object with the Password property set, the value is displayed as a string containing '*'.  However, the object stores the value of the Password property as plain text.

       * KeyName --- Specify the name of an additional key to be added to the HTTP request header.  It should be coupled with KeyValue.  It must be a string or character vector.

       * KeyValue --- Specify the value of the key KeyName.

          KeyName must be present in order to assign to this field.

       * HeaderFields --- Specify the header fields for the connection.

          Names and values of header fields, specified as an m-by-2 array of strings or cell array of character vectors to add to the HTTP request header. HeaderFields{i,1} is the name of a field and HeaderFields{i,2} is its value.

               weboptions ("HeaderFields",
                           {"Content-Length", "78" ;
                            "Content-Type", "application/json"})

          creates a weboptions object that contains two header fields: Content-Length with value 78 and Content-Type with value application/json.

       * ContentType --- Specify the content type of the data.

          The following values are available: auto, text, json

          Default is auto.  It automatically determines the content type. All other formats like audio, binary, etc. available in MATLAB are not currently supported.

       * ContentReader --- Not yet implemented.  Only for MATLAB compatibility.

       * MediaType --- Not yet implemented.  Only for MATLAB compatibility.

       * RequestMethod --- Specifies the type of request to be made.

          The following methods are available: get, put, post, delete, patch

          webread uses the HTTP GET method.  webwrite uses the HTTP POST method as default.

       * ArrayFormat -- Not yet implemented.  Only for MATLAB compatibility.

       * CertificateFilename --- Not yet implemented.  Only for MATLAB compatibility.

     webread, webwrite

Base64 and Binary Data Transmission
-----------------------------------

Some transmission channels can not accept binary data.  It is customary to encode binary data in Base64 for transmission and to decode the data upon reception.

 -- S =: base64_encode (X)
     Encode a double matrix or array X into the base64 format string S.

     base64_decode, matlab.net.base64decode, matlab.net.base64encode

 -- X =: base64_decode (S)
 -- X =: base64_decode (S, DIMS)
     Decode the double matrix or array X from the base64 encoded string S.

     The optional input parameter DIMS should be a vector containing the dimensions of the decoded array. base64_encode, matlab.net.base64decode, matlab.net.base64encode

 -- B64_STR =: matlab.net.base64encode (IN)

     Convert IN to a base64 encoded string B64_STR.

     The input IN can be a string or numeric vector. The output B64_STR will be encoded according to RFC 4648.

     matlab.net.base64decode, base64_decode, base64_encode, unicode2native

 -- OUT_VEC =: matlab.net.base64decode (B64_STR)

     Convert base64 encoded B64_STR to uint8 vector OUT_VEC.

     The input B64_STR must be a string vector. The output OUT_VEC will be a uint8 vector that is decoded according to RFC 4648.

     matlab.net.base64encode, base64_decode, base64_encode, native2unicode

Controlling Subprocesses
========================

Octave includes some high-level commands like system and popen for starting subprocesses.  If you want to run another program to perform some task and then look at its output, you will probably want to use these functions.

Octave also provides several very low-level Unix-like functions which can also be used for starting subprocesses, but you should probably only use them if you can't find any way to do what you need with the higher-level functions.

 -- system: ("STRING")
 -- system: ("STRING", RETURN_OUTPUT)
 -- system: ("STRING", RETURN_OUTPUT, TYPE)
 -- [STATUS, OUTPUT] =: system (...)
     Execute a shell command specified by STRING.

     If SYSTEM is called with one or more output arguments, or if the optional argument RETURN_OUTPUT is true and the subprocess is started synchronously, then the output from the command is returned as a variable. Otherwise, if the subprocess is executed synchronously, its output is sent to the standard output.  To send the output of a command executed with system through the pager, use a command like

          [~, text] = system ("cmd");
          more on;
          disp (text);

     or

          more on;
          printf ("%s\n", nthargout (2, "system", "cmd"));

     If the optional argument TYPE is "async", the process is started in the background and the process ID of the child process is returned immediately.  Otherwise, the child process is started and Octave waits until it exits.  If the TYPE argument is omitted, it defaults to the value "sync".

     The system function can return two values.  The first is the exit status of the command and the second is any output from the command that was written to the standard output stream.  For example,

          [status, output] = system ("echo foo & exit 2");

     will set the variable OUTPUT to the string foo, and the variable STATUS to the integer 2.

     For commands run asynchronously, STATUS is the process id of the command shell that is started to run the command.

     The shell used for executing commands varies with operating system and is typically /bin/sh for UNIX systems and cmd.exe for Windows systems. unix, dos

 -- unix: ("COMMAND")
 -- STATUS =: unix ("COMMAND")
 -- [STATUS, TEXT] =: unix ("COMMAND")
 -- [...] =: unix ("COMMAND", "-echo")
     Execute a system command if running under a Unix-like operating system, otherwise do nothing.

     Octave waits for the external command to finish before returning the exit status of the program in STATUS and any output in TEXT.

     When called with no output argument, or the "-echo" argument is given, then TEXT is also sent to standard output. dos, system, isunix, ismac, ispc

 -- dos: ("COMMAND")
 -- STATUS =: dos ("COMMAND")
 -- [STATUS, TEXT] =: dos ("COMMAND")
 -- [...] =: dos ("COMMAND", "-echo")
     Execute a system command if running under a Windows-like operating system, otherwise do nothing.

     Octave waits for the external command to finish before returning the exit status of the program in STATUS and any output in TEXT.

     When called with no output argument, or the "-echo" argument is given, then TEXT is also sent to standard output. unix, system, isunix, ismac, ispc

 -- open: FILE
 -- OUTPUT =: open (FILE)
     Open the file FILE in Octave or in an external application based on the file type as determined by the filename extension.

     By default, recognized file types are

     .m
          Open file in the editor.  No OUTPUT value is returned.

     .mat
     octave-workspace
          Open the data file with load.  If no return value OUTPUT is requested, variables are loaded in the base workspace.  Otherwise OUTPUT will be a structure containing loaded data. See load function.

     .ofig
          Open the figure with hgload. See hgload function.

     .fig, .ofig
          Load the figure

     .exe
          Execute the program (on Windows systems only).  No OUTPUT value is returned.

     Custom file extensions may also be handled if a function openxxx, where xxx is the extension, is found in the load path.  The function must accept the file name as input.  For example, in order to load ".dat" data files in the base workspace, as is done by default for ".mat" files, one may define "opendat.m" with the following contents:

          function retval = opendat (fname)
            evalin ("base", sprintf ("load ('%s');", fname));
          endfunction

     Other file types are opened in the appropriate external application.

 -- OUTPUT =: perl (SCRIPTFILE)
 -- OUTPUT =: perl (SCRIPTFILE, ARGUMENT1, ARGUMENT2, ...)
 -- [OUTPUT, STATUS] =: perl (...)
     Invoke Perl script SCRIPTFILE, possibly with a list of command line arguments.

     Return output in OUTPUT and optional status in STATUS.  If SCRIPTFILE is not an absolute filename it is searched for in the current directory and then in the Octave loadpath. system, python

 -- OUTPUT =: python (SCRIPTFILE)
 -- OUTPUT =: python (SCRIPTFILE, ARGUMENT1, ARGUMENT2, ...)
 -- [OUTPUT, STATUS] =: python (...)
     Invoke Python script SCRIPTFILE, possibly with a list of command line arguments.

     Return output in OUTPUT and optional status in STATUS.  If SCRIPTFILE is not an absolute filename it is searched for in the current directory and then in the Octave loadpath.

     Programming Note: On UNIX systems, the script will be executed by python3 and on Windows by python.  You can override these defaults by setting the PYTHON environment variable, for example from within Octave using setenv PYTHON /usr/local/bin/python3.

     system, perl

 -- FID =: popen (COMMAND, MODE)
     Start a process and create a pipe.

     The name of the command to run is given by COMMAND.  The argument MODE may be

     "r"
          The pipe will be connected to the standard output of the process, and open for reading.

     "w"
          The pipe will be connected to the standard input of the process, and open for writing.

     The file identifier corresponding to the input or output stream of the process is returned in FID.

     For example:

          fid = popen ("ls -ltr / | tail -3", "r");
          while (ischar (s = fgets (fid)))
            fputs (stdout, s);
          endwhile

             -| drwxr-xr-x  33 root  root  3072 Feb 15 13:28 etc
             -| drwxr-xr-x   3 root  root  1024 Feb 15 13:28 lib
             -| drwxrwxrwt  15 root  root  2048 Feb 17 14:53 tmp

     popen2

 -- STATUS =: pclose (FID)
     Close a file identifier FID that was opened by popen.

     If successful, fclose returns 0, otherwise, it returns -1.

     Programming Note: The function fclose may also be used for the same purpose. fclose, popen

 -- [IN, OUT, PID] =: popen2 (COMMAND, ARGS)
     Start a subprocess with two-way communication.

     The name of the process is given by COMMAND, and ARGS is an array or cell array of strings containing options for the command.

     The file identifiers for the input and output streams of the subprocess are returned in IN and OUT.  If execution of the command is successful, PID contains the process ID of the subprocess.  Otherwise, PID is -1.

     For example:

          [in, out, pid] = popen2 ("sort", "-r");
          fputs (in, "these\nare\nsome\nstrings\n");
          fclose (in);
          EAGAIN = errno ("EAGAIN");
          done = false;
          do
            s = fgets (out);
            if (ischar (s))
              fputs (stdout, s);
            elseif (errno () == EAGAIN)
              pause (0.1);
              fclear (out);
            else
              done = true;
            endif
          until (done)
          fclose (out);
          waitpid (pid);

             -| these
             -| strings
             -| some
             -| are

     Note that popen2, unlike popen, will not "reap" the child process.  If you don't use waitpid to check the child's exit status, it will linger until Octave exits. popen, waitpid

 -- VAL =: EXEC_PATH ()
 -- OLD_VAL =: EXEC_PATH (NEW_VAL)
 -- OLD_VAL =: EXEC_PATH (NEW_VAL, "local")
     Query or set the internal variable that specifies a colon separated list of directories to append to the shell PATH when executing external programs.

     The initial value of is taken from the environment variable OCTAVE_EXEC_PATH, but that value can be overridden by the command line argument --exec-path PATH.

     When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

     IMAGE_PATH, OCTAVE_HOME, OCTAVE_EXEC_HOME

In most cases, the following functions simply decode their arguments and make the corresponding Unix system calls.  For a complete example of how they can be used, look at the definition of the function popen2.

 -- [PID, MSG] =: fork ()
     Create a copy of the current process.

     Fork can return one of the following values:

     > 0
          You are in the parent process.  The value returned from fork is the process id of the child process.  You should probably arrange to wait for any child processes to exit.

     0
          You are in the child process.  You can call exec to start another process.  If that fails, you should probably call exit.

     < 0
          The call to fork failed for some reason.  You must take evasive action.  A system dependent error message will be waiting in MSG.

 -- [ERR, MSG] =: exec (FILE, ARGS)
     Replace current process with a new process.

     Calling exec without first calling fork will terminate your current Octave process and replace it with the program named by FILE. For example,

          exec ("ls", "-l")

     will run ls and return you to your shell prompt.

     If successful, exec does not return.  If exec does return, ERR will be nonzero, and MSG will contain a system-dependent error message.

 -- [READ_FD, WRITE_FD, ERR, MSG] =: pipe ()
     Create a pipe and return the reading and writing ends of the pipe into READ_FD and WRITE_FD respectively.

     If successful, ERR is 0 and MSG is an empty string. Otherwise, ERR is nonzero and MSG contains a system-dependent error message. mkfifo

 -- [FID, MSG] =: dup2 (OLD, NEW)
     Duplicate a file descriptor.

     If successful, FID is greater than zero and contains the new file ID. Otherwise, FID is negative and MSG contains a system-dependent error message. fopen, fclose, fcntl

 -- [PID, STATUS, MSG] =: waitpid (PID, OPTIONS)
     Wait for process PID to terminate.

     The PID argument can be:

     -1
          Wait for any child process.

     0
          Wait for any child process whose process group ID is equal to that of the Octave interpreter process.

     > 0
          Wait for termination of the child process with ID PID.

     The OPTIONS argument can be a bitwise OR of zero or more of the following constants:

     0
          Wait until signal is received or a child process exits (this is the default if the OPTIONS argument is missing).

     WNOHANG
          Do not hang if status is not immediately available.

     WUNTRACED
          Report the status of any child processes that are stopped, and whose status has not yet been reported since they stopped.

     WCONTINUE
          Return if a stopped child has been resumed by delivery of SIGCONT. This value may not be meaningful on all systems.

     If the returned value of PID is greater than 0, it is the process ID of the child process that exited.  If an error occurs, PID will be less than zero and MSG will contain a system-dependent error message. The value of STATUS contains additional system-dependent information about the subprocess that exited. WCONTINUE, WCOREDUMP, WEXITSTATUS, WIFCONTINUED, WIFSIGNALED, WIFSTOPPED, WNOHANG, WSTOPSIG, WTERMSIG, WUNTRACED

 -- V =: WCONTINUE ()
     Return the numerical value of the WCONTINUE macro.

     WCONTINUE is the option argument that may be passed to waitpid to indicate that it should also return if a stopped child has been resumed by delivery of a SIGCONT signal. waitpid, WNOHANG, WUNTRACED

 -- TF =: WCOREDUMP (STATUS)
     Given STATUS from a call to waitpid, return true if the child produced a core dump.

     This function should only be employed if WIFSIGNALED returned true. The macro used to implement this function is not specified in POSIX.1-2001 and is not available on some Unix implementations (e.g., AIX, SunOS). waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED, WSTOPSIG, WIFCONTINUED

 -- TF =: WEXITSTATUS (STATUS)
     Given STATUS from a call to waitpid, return the exit status of the child.

     This function should only be employed if WIFEXITED returned true. waitpid, WIFEXITED, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED

 -- TF =: WIFCONTINUED (STATUS)
     Given STATUS from a call to waitpid, return true if the child process was resumed by delivery of SIGCONT. waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG

 -- TF =: WIFSIGNALED (STATUS)
     Given STATUS from a call to waitpid, return true if the child process was terminated by a signal. waitpid, WIFEXITED, WEXITSTATUS, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED

 -- TF =: WIFSTOPPED (STATUS)
     Given STATUS from a call to waitpid, return true if the child process was stopped by delivery of a signal.

     This is only possible if the call was done using WUNTRACED or when the child is being traced (see ptrace(2)). waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WSTOPSIG, WIFCONTINUED

 -- TF =: WIFEXITED (STATUS)
     Given STATUS from a call to waitpid, return true if the child terminated normally. waitpid, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED

 -- V =: WNOHANG ()
     Return the numerical value of the WNOHANG macro.

     WNOHANG is the option argument that may be passed to waitpid to indicate that it should return its status immediately instead of waiting for a process to exit. waitpid, WUNTRACED, WCONTINUE

 -- TF =: WSTOPSIG (STATUS)
     Given STATUS from a call to waitpid, return the number of the signal which caused the child to stop.

     This function should only be employed if WIFSTOPPED returned true. waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WCOREDUMP, WIFSTOPPED, WIFCONTINUED

 -- TF =: WTERMSIG (STATUS)
     Given STATUS from a call to waitpid, return the number of the signal that caused the child process to terminate.

     This function should only be employed if WIFSIGNALED returned true. waitpid, WIFEXITED, WEXITSTATUS, WIFSIGNALED, WCOREDUMP, WIFSTOPPED, WSTOPSIG, WIFCONTINUED

 -- V =: WUNTRACED ()
     Return the numerical value of the WUNTRACED macro.

     WUNTRACED is the option argument that may be passed to waitpid to indicate that it should also return if the child process has stopped but is not traced via the ptrace system call waitpid, WNOHANG, WCONTINUE

 -- fcntl: (FID, REQUEST, ARG)
 -- [STATUS, MSG] =: fcntl (FID, REQUEST, ARG)
     Change the properties of the open file FID.

     The following values may be passed as REQUEST:

     F_DUPFD
          Return a duplicate file descriptor.

     F_GETFD
          Return the file descriptor flags for FID.

     F_SETFD
          Set the file descriptor flags for FID.

     F_GETFL
          Return the file status flags for FID.  The following codes may be returned (some of the flags may be undefined on some systems).

          O_RDONLY
               Open for reading only.

          O_WRONLY
               Open for writing only.

          O_RDWR
               Open for reading and writing.

          O_APPEND
               Append on each write.

          O_CREAT
               Create the file if it does not exist.

          O_NONBLOCK
               Non-blocking mode.

          O_SYNC
               Wait for writes to complete.

          O_ASYNC
               Asynchronous I/O.

     F_SETFL
          Set the file status flags for FID to the value specified by ARG. The only flags that can be changed are O_APPEND and O_NONBLOCK.

     If successful, STATUS is 0 and MSG is an empty string.  Otherwise, STATUS is -1 and MSG contains a system-dependent error message. fopen, dup2

 -- kill: (PID, SIG)
 -- [STATUS, MSG] =: kill (PID, SIG)
     Send signal SIG to process PID.

     If PID is positive, then signal SIG is sent to PID.

     If PID is 0, then signal SIG is sent to every process in the process group of the current process.

     If PID is -1, then signal SIG is sent to every process except process 1.

     If PID is less than -1, then signal SIG is sent to every process in the process group -PID.

     If SIG is 0, then no signal is sent, but error checking is still performed.

     If successful, STATUS is 0 and MSG is an empty string. Otherwise, STATUS is -1 and MSG contains a system-dependent error message.

 -- S =: SIG ()
     Return a structure containing Unix signal names and their defined values.

Process, Group, and User IDs
============================

 -- pgid =: getpgrp ()
     Return the process group id of the current process.

 -- pid =: getpid ()
     Return the process id of the current process. getppid

 -- pid =: getppid ()
     Return the process id of the parent process. getpid

 -- euid =: geteuid ()
     Return the effective user id of the current process. getuid

 -- uid =: getuid ()
     Return the real user id of the current process. geteuid

 -- egid =: getegid ()
     Return the effective group id of the current process. getgid

 -- gid =: getgid ()
     Return the real group id of the current process. getegid

Environment Variables
=====================

 -- VAL =: getenv ("VAR")
     Return the value of the environment variable VAR.

     For example,

          getenv ("PATH")

     returns a string containing the value of your path. setenv, unsetenv, isenv

 -- TF =: isenv (VAR)
     Return true if the variable VAR is an environment variable, and false otherwise.

     For example,

          tf = isenv ("PATH")

     will typically return true on UNIX systems because "PATH" is an environment variable for UNIX. getenv, setenv, unsetenv

 -- setenv: ("VAR", VALUE)
 -- setenv: (VAR)
 -- putenv: (...)
     Set the value of the environment variable VAR to VALUE.

     If no VALUE is specified then the variable will be assigned the null string.

     Programming Note: putenv is an alias for setenv and can be used interchangeably. unsetenv, getenv, isenv

 -- unsetenv: ("VAR")
 -- STATUS =: unsetenv ("VAR")
     Delete the environment variable VAR.

     Return 0 if the variable was deleted, or did not exist, and -1 if an error occurred. setenv, getenv, isenv

 -- HOMEDIR =: get_home_directory ()
     Return the current home directory.

     On most systems, this is equivalent to getenv ("HOME").  On Windows systems, if the environment variable HOME is not set then it is equivalent to fullfile (getenv ("HOMEDRIVE"), getenv ("HOMEPATH")) getenv

Current Working Directory
=========================

 -- cd: DIR
 -- cd:
 -- OLD_DIR =: cd
 -- OLD_DIR =: cd (DIR)
 -- chdir: ...
     Change the current working directory to DIR.

     If called with no input or output arguments, the current directory is changed to the user's home directory ("~").

     For example,

          cd ~/octave

     changes the current working directory to ~/octave.  If the directory does not exist, an error message is printed and the working directory is not changed.

     Programming Note: chdir is an alias for cd and can be used with all of the same calling formats.

     Compatibility Note: When called with no arguments, MATLAB prints the present working directory rather than changing to the user's home directory. pwd, mkdir, rmdir, dir, ls

 -- ls:
 -- ls: FILENAMES
 -- ls: OPTIONS
 -- ls: OPTIONS FILENAMES
 -- LIST =: ls (...)

     List directory contents.

     The ls function forwards to the ls command if it is available. It falls back to calling the native operating system's directory listing command.  Available OPTIONS may vary from system to system.

     Filenames are subject to shell expansion if they contain any wildcard characters *, ?, [].  If these wildcard characters are escaped with a backslash \ (e.g., \*) then they are not treated as wildcards, but instead as the corresponding literal character.

     If the optional output LIST is requested then ls returns a character array with one row for each file/directory name.

     Example usage on a UNIX-like system:

          ls -l
               -| total 12
               -| -rw-r--r--   1 jwe  users  4488 Aug 19 04:02 foo.m
               -| -rw-r--r--   1 jwe  users  1315 Aug 17 23:14 bar.m

     dir, readdir, glob, what, stat, filesep, ls_command

 -- VAL =: ls_command ()
 -- OLD_VAL =: ls_command (NEW_VAL)
     Query or set the shell command used by Octave's ls command. ls

 -- dir:
 -- dir: DIRECTORY
 -- [LIST] =: dir (DIRECTORY)
     Display file listing for directory DIRECTORY.

     If DIRECTORY is not specified then list the present working directory.

     If a return value is requested, return a structure array with the fields

     name
          File or directory name.

     folder
          Location of file or directory

     date
          Timestamp of file modification (string value).

     bytes
          File size in bytes.

     isdir
          True if name is a directory.

     datenum
          Timestamp of file modification as serial date number (double).

     statinfo
          Information structure returned from stat.

     If DIRECTORY is a filename, rather than a directory, then return information about the named file.  DIRECTORY may also be a list rather than a single directory or file.

     DIRECTORY is subject to shell expansion if it contains any wildcard characters *, ?, [].  If these wildcard characters are escaped with a backslash \ (e.g., \*) on a POSIX platform, then they are not treated as wildcards, but as the corresponding literal character.  On Windows, it is not possible to escape wildcard characters because backslash \ is treated as a file separator.  On Windows, use ls for file or folder names that contain characters that would be treated as wildcards by dir.

     Note that for symbolic links, dir returns information about the file that the symbolic link points to rather than the link itself.  However, if the link points to a nonexistent file, dir returns information about the link. ls, readdir, glob, what, stat, lstat

 -- DIR =: pwd ()
     Return the current working directory. cd, dir, ls, mkdir, rmdir

Password Database Functions
===========================

Octave's password database functions return information in a structure with the following fields.

name
     The user name.

passwd
     The encrypted password, if available.

uid
     The numeric user id.

gid
     The numeric group id.

gecos
     The GECOS field.

dir
     The home directory.

shell
     The initial shell.

In the descriptions of the following functions, this data structure is referred to as a PW_STRUCT.

 -- 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, getpwent returns 0. setpwent, endpwent

 -- PW_STRUCT =: getpwuid (UID).
     Return a structure containing the first entry from the password database with the user ID UID.

     If the user ID does not exist in the database, getpwuid returns 0. getpwnam

 -- PW_STRUCT =: getpwnam (NAME)
     Return a structure containing the first entry from the password database with the user name NAME.

     If the user name does not exist in the database, getpwname returns 0. getpwuid

 -- [STATUS, MSG] =: setpwent ()
     Return the internal pointer to the beginning of the password database. getpwent, endpwent

 -- [STATUS, MSG] =: endpwent ()
     Close the password database. getpwent, setpwent

Group Database Functions
========================

Octave's group database functions return information in a structure with the following fields.

name
     The user name.

passwd
     The encrypted password, if available.

gid
     The numeric group id.

mem
     The members of the group.

In the descriptions of the following functions, this data structure is referred to as a GRP_STRUCT.

 -- GRP_STRUCT =: getgrent ()
     Return an entry from the group database, opening it if necessary.

     Once the end of data has been reached, getgrent returns 0. setgrent, endgrent

 -- GRP_STRUCT =: getgrgid (GID).
     Return the first entry from the group database with the group ID GID.

     If the group ID does not exist in the database, getgrgid returns 0. getgrnam

 -- GRP_STRUCT =: getgrnam (NAME)
     Return the first entry from the group database with the group name NAME.

     If the group name does not exist in the database, getgrnam returns 0. getgrgid

 -- [STATUS, MSG] =: setgrent ()
     Return the internal pointer to the beginning of the group database. getgrent, endgrent

 -- [STATUS, MSG] =: endgrent ()
     Close the group database. getgrent, setgrent

System Information
==================

 -- computer: ()
 -- COMP =: computer ()
 -- [COMP, MAXSIZE] =: computer ()
 -- [COMP, MAXSIZE, ENDIAN] =: computer ()
 -- ARCH =: computer ("arch")
     Print or return a string of the form CPU-VENDOR-OS that identifies the type of computer that Octave is running on.

     If invoked with an output argument, the value is returned instead of printed.  For example:

          computer ()
             -| x86_64-pc-linux-gnu

          mycomp = computer ()
             => mycomp = x86_64-pc-linux-gnu

     If two output arguments are requested, also return the maximum number of elements for an array.  This will depend on whether Octave has been compiled with 32-bit or 64-bit index vectors.

     If three output arguments are requested, also return the byte order of the current system as a character ("B" for big-endian or "L" for little-endian).

     If the argument "arch" is specified, return a string indicating the architecture of the computer on which Octave is running.

     Results may be different if Octave was invoked with the --traditional option. isunix, ismac, ispc

 -- [UTS, ERR, MSG] =: uname ()
     Return system information in the structure.

     For example:

          uname ()
             => {
                   sysname = x86_64
                   nodename = segfault
                   release = 2.6.15-1-amd64-k8-smp
                   version = Linux
                   machine = #2 SMP Thu Feb 23 04:57:49 UTC 2006
                }

     If successful, ERR is 0 and MSG is an empty string. Otherwise, ERR is nonzero and MSG contains a system-dependent error message.

 -- N =: nproc ()
 -- N =: nproc (QUERY)
     Return the current number of available (logical) processors.

     This returns the number of logical processors.  For processors with hyperthreading, this is larger than the number of physical cores.

     If called with the optional argument QUERY, modify how processors are counted as follows:

     all
          total number of processors.

     current
          processors available to the current process.

     overridable
          same as current, but overridable through the OMP_NUM_THREADS environment variable.

 -- TF =: ispc ()
     Return true if Octave is running on a Windows system and false otherwise. isunix, ismac

 -- TF =: isunix ()
     Return true if Octave is running on a Unix-like system and false otherwise. ismac, ispc

 -- TF =: ismac ()
     Return true if Octave is running on a Mac OS X system and false otherwise. isunix, ispc

 -- TF =: isieee ()
     Return true if your computer claims to conform to the IEEE 754 standard for floating point calculations.

     No actual tests are performed.

 -- TF =: isdeployed ()
     Return true if the current program has been compiled and is running separately from the Octave interpreter and false if it is running in the Octave interpreter.

     Currently, this function always returns false in Octave.

 -- TF =: isstudent ()
     Return true if running in the student edition of MATLAB.

     isstudent always returns false in Octave. false

 -- DIR =: OCTAVE_HOME ()
     Return the name of the top-level Octave installation directory.

     OCTAVE_HOME corresponds to the configuration variable PREFIX. EXEC_PATH, IMAGE_PATH, OCTAVE_EXEC_HOME

 -- DIR =: OCTAVE_EXEC_HOME ()
     Return the name of the top-level Octave installation directory for architecture-dependent files.

     If not specified separately, the value is the same as OCTAVE_HOME. OCTAVE_EXEC_HOME corresponds to the configuration variable EXEC_PREFIX. EXEC_PATH, IMAGE_PATH, OCTAVE_HOME

 -- DIR =: matlabroot ()
     Return the name of the top-level Octave installation directory.

     This is an alias for the function OCTAVE_HOME provided for compatibility. OCTAVE_HOME

 -- cfg_dir =: user_config_dir ()
     Return the (platform-specific) directory for user configuration. user_data_dir

 -- data_dir =: user_data_dir ()
     Return the (platform-specific) directory for user data. user_config_dir

 -- VERSTR =: OCTAVE_VERSION ()
     Return the version number of Octave as a string. ver, version

 -- V =: version ()
 -- [V, D] =: version ()
 -- V =: version (FEATURE)
     Get version information for Octave.

     If called without input argument, the first return value V gives the version number of Octave as a string.  The second return value D holds the release date as a string.

     The following options can be passed for FEATURE:

     "-date"
          for the release date of the running build,

     "-description"
          for a description of the release (always an empty string),

     "-release"
          for the name of the running build (always an empty string),

     "-java"
          for version information of the Java VM,

     "-fftw"
          for version information for the linked FFTW,

     "-blas"
          for version information for the linked BLAS,

     "-lapack"
          for version information for the linked LAPACK.

     "-hgid"
          the mercurial ID of the sources used to build Octave.

     The information returned for the "-blas" and "-lapack" options might be unreliable.  It might report which library was linked in when Octave was built instead of which library is currently used.

     The variant with no input and output argument is an alias for the function OCTAVE_VERSION provided for compatibility. OCTAVE_VERSION, ver

 -- ver:
 -- ver: Octave
 -- ver: PACKAGE
 -- v =: ver (...)

     Display a header containing the current Octave version number, license string, and operating system.  The header is followed by a list of installed packages, versions, and installation directories.

     Use the package name PACKAGE or Octave to query a specific component.

     When called with an output argument, return a vector of structures describing Octave and each installed package.  Each structure includes the following fields.

     Name
          Package name.

     Version
          Version of the package.

     Release
          Release of the package (currently unused, defaults to []).

     Date
          Date that the version was released.

     version, usejava, pkg

 -- TF =: compare_versions (V1, V2, OPERATOR)
     Compare two version strings using the given OPERATOR.

     This function assumes that versions V1 and V2 are arbitrarily long strings made of numeric and period characters possibly followed by an arbitrary string (e.g., "1.2.3", "0.3", "0.1.2+", or "1.2.3.4-test1").

     The version is first split into numeric and character portions and then the parts are padded to be the same length (i.e., "1.1" would be padded to be "1.1.0" when being compared with "1.1.1", and separately, the character parts of the strings are padded with nulls).

     The operator can be any logical operator from the set

       * "==" equal

       * "<" less than

       * "<=" less than or equal to

       * ">" greater than

       * ">=" greater than or equal to

       * "!=", "~=" not equal

     Note that version "1.1-test2" will compare as greater than "1.1-test10".  Also, since the numeric part is compared first, "a" compares less than "1a" because the second string starts with a numeric part even though double ("a") is greater than double ("1").

 -- TF =: verLessThan (PACKAGE, VERSION)
     Return true if the installed version of the package is less than VERSION.

     PACKAGE is the name of the package to check.  Use "Octave" as the PACKAGE to check the version of Octave itself.

     VERSION is the version to compare it to.  A version is a string in the format accepted by compare_versions: an arbitrarily long string composed of numeric and period characters, possibly followed by an arbitrary string (e.g., "1.2.3", "0.3", "0.1.2+", or "1.2.3.4-test1").

     Examples:

          tf = verLessThan ("Octave", "5")
          => tf = 0

          tf = verLessThan ("io", "2.4.12")
          => ...

          if (! verLessThan ("Octave", "5"))
            ## ... use new Octave 5 features ...
          endif

     compare_versions, version, ver, pkg

 -- license:
 -- license: inuse
 -- license: inuse FEATURE
 -- license: ("inuse")
 -- LICENSE_STRUCT =: license ("inuse")
 -- LICENSE_STRUCT =: license ("inuse", FEATURE)
 -- STATUS =: license ("test", FEATURE)
 -- STATUS =: license ("checkout", FEATURE)
 -- [STATUS, ERRMSG] =: license ("checkout", FEATURE)
     Get license information for Octave and Octave packages.

     GNU Octave is free software distributed under the GNU General Public License (GPL), and a license manager makes no sense.  This function is provided only for MATLAB compatibility.

     When called with no extra input arguments, it returns the Octave license, otherwise the first input defines the operation mode and must be one of the following strings: inuse, test, and checkout. The optional FEATURE argument can either be "octave" (core) or the name of an Octave package.

     "inuse"
          Print a list of loaded features, i.e., "octave" and the list of loaded packages.  If an output is requested, it returns a struct array with the fields "feature", and "user".

     "test"
          Return true if the specified FEATURE is installed, false otherwise.

          An optional third argument "enable" or "disable" is accepted but ignored.

     "checkout"
          Return true if the specified FEATURE is installed, false otherwise. An optional second output will have an error message if a package is not installed.

     pkg, ver, version

 -- memory: ()
 -- [USERDATA, SYSTEMDATA] =: memory ()
     Display or return information about the memory usage of Octave.

     If the function is called without output arguments, a table with an overview of the current memory consumption is displayed.

     The output argument USERDATA is a structure with the following fields containing data for the Octave process:

     MaxPossibleArrayBytes
          Maximum size for an array to be allocated.  Be aware that this includes all physical memory and swap space.  Allocating that amount of memory might result in system instability, data corruption, and/or file system corruption.  Note that depending on the platform (32-bit systems), the largest contiguous memory block might further limit the maximum possible allocatable array.  This check is not currently implemented.

     MemAvailableAllArrays
          The total size of available memory in bytes.

     ram_available_all_arrays
          The maximum size for an array that can be allocated in physical memory (excluding swap space).  Note that depending on the platform (32-bit systems), the largest contiguous memory block might further limit the maximum possible allocatable array.  This check is not currently implemented.

     MemUsedMATLAB
     mem_used_octave
          The memory (including swap space) currently used by Octave in bytes.

     ram_used_octave
          The physical memory (excluding swap space) currently used by Octave in bytes.

     The output argument SYSTEMDATA is a nested structure with the following fields containing information about the system's memory:

     PhysicalMemory.Available
          The currently available physical memory in bytes.

     PhysicalMemory.Total
          The total physical memory in bytes.

     SystemMemory.Available
          The currently available memory (including swap space) in bytes.

     SystemMemory.Total
          The total memory (including swap space) in bytes.

     VirtualAddressSpace.Available
          The currently available virtual address space in bytes.

     VirtualAddressSpace.Total
          The total virtual address space in bytes.

     Example #1 : print formatted table of memory usage

          memory ()
          =>
          System    RAM: 3934008 KiB,  swap: 4087804 KiB
          Octave    RAM:  170596 KiB,  virt: 1347944 KiB
          Free      RAM: 1954940 KiB,  swap: 4087804 KiB
          Available RAM: 2451948 KiB, total: 6042744 KiB

     Example #2 : return structs with memory usage information

          [userdata, systemdata] = memory ()
          =>
           userdata =

             scalar structure containing the fields:

               MaxPossibleArrayBytes = 6.1622e+09
               MemAvailableAllArrays = 6.1622e+09
               ram_available_all_arrays = 2.4883e+09
               MemUsedMATLAB = 1.3825e+09
               mem_used_octave = 1.3825e+09
               ram_used_octave = 1.7824e+08

           systemdata =

             scalar structure containing the fields:

               PhysicalMemory =

                 scalar structure containing the fields:

                   Available = 2.4954e+09
                   Total = 4.0284e+09

               SystemMemory =

                 scalar structure containing the fields:

                   Available = 6.6813e+09
                   Total = 8.2143e+09

               VirtualAddressSpace =

                 scalar structure containing the fields:

                   Available = 2.8147e+14
                   Total = 2.8147e+14

     Programming Note: This function is implemented for Linux and Windows only.

     computer, getpid, getrusage, nproc, uname

 -- PROCSTATS =: 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.  The list of possible fields is:

     idrss
          Unshared data size.

     inblock
          Number of block input operations.

     isrss
          Unshared stack size.

     ixrss
          Shared memory size.

     majflt
          Number of major page faults.

     maxrss
          Maximum data size.

     minflt
          Number of minor page faults.

     msgrcv
          Number of messages received.

     msgsnd
          Number of messages sent.

     nivcsw
          Number of involuntary context switches.

     nsignals
          Number of signals received.

     nswap
          Number of swaps.

     nvcsw
          Number of voluntary context switches.

     oublock
          Number of block output operations.

     stime
          A structure containing the system CPU time used.  The structure has the elements sec (seconds) usec (microseconds).

     utime
          A structure containing the user CPU time used.  The structure has the elements sec (seconds) usec (microseconds).

 -- VALUE =: winqueryreg (ROOTKEY, SUBKEY, VALUENAME)
 -- VALUE =: winqueryreg (ROOTKEY, SUBKEY)
 -- NAMES =: winqueryreg ("name", ROOTKEY, SUBKEY)

     Query names or value from the Windows registry.

     On Windows, return the value of the registry key SUBKEY from the root key ROOTKEY.  You can specify the name of the queried registry value with the optional argument VALUENAME.  Otherwise, if called with only two arguments or VALUENAME is empty, then the default value of SUBKEY is returned.  If the registry value is of type "REG_DWORD" then VALUE is of class int32.  If the value is of the type "REG_SZ" or "REG_EXPAND_SZ" a string is returned.

     If the first argument is "name", a cell array of strings with the names of the values at that key is returned.

     The variable ROOTKEY must be a string with a valid root key identifier:

     HKCR
     HKEY_CLASSES_ROOT

     HKEY_CURRENT_CONFIG

     HKCU
     HKEY_CURRENT_USER

     HKLM
     HKEY_LOCAL_MACHINE

     HKU
     HKEY_USERS

     HKEY_PERFORMANCE_DATA

     Examples:

     Get a list of value names at the key 'HKCU\Environment':

          VALUENAMES = winqueryreg ("name", "HKEY_CURRENT_USER", ...
                                    "Environment");

     For each VALUENAMES, display the value:

          for K = 1:numel (VALUENAMES)
            VAL = winqueryreg ("HKEY_CURRENT_USER", "Environment", ...
                               VALUENAMES{K});
            STR = sprintf ("%s = %s", VALUENAMES{K}, num2str (VAL));
            disp (STR);
          endfor

     On non-Windows platforms this function fails with an error.

Hashing Functions
=================

It is often necessary to find if two strings or files are identical. This might be done by comparing them character by character and looking for differences.  However, this can be slow, and so comparing a hash of the string or file can be a rapid way of finding if the files differ.

Another use of the hashing function is to check for file integrity.  The user can check the hash of the file against a known value and find if the file they have is the same as the one that the original hash was produced with.

Octave supplies the hash function to calculate hash values of strings and files, the latter in combination with the fileread function.  The hash function supports many commonly used hash methods.

 -- HASHVAL =: hash ("HASHFCN", STR)
     Calculate the hash value of the string STR using the hash function HASHFCN.

     The available hash functions are given in the table below.

     MD2
          Message-Digest Algorithm 2 (RFC 1319).

     MD4
          Message-Digest Algorithm 4 (RFC 1320).

     MD5
          Message-Digest Algorithm 5 (RFC 1321).

     SHA1
          Secure Hash Algorithm 1 (RFC 3174)

     SHA224
          Secure Hash Algorithm 2 (224 Bits, RFC 3874)

     SHA256
          Secure Hash Algorithm 2 (256 Bits, RFC 6234)

     SHA384
          Secure Hash Algorithm 2 (384 Bits, RFC 6234)

     SHA512
          Secure Hash Algorithm 2 (512 Bits, RFC 6234)

     To calculate for example the MD5 hash value of the string "abc" the hash function is called as follows:

          hash ("md5", "abc")
               -| ans = 900150983cd24fb0d6963f7d28e17f72

     For the same string, the SHA-1 hash value is calculated with:

          hash ("sha1", "abc")
               -| ans = a9993e364706816aba3e25717850c26c9cd0d89d

     And to compute the hash value of a file, e.g., file = "file.txt", call hash in combination with the fileread:

          hash ("md5", fileread (file));