File: system.texi

package info (click to toggle)
octave 10.3.0-1
links: PTS, VCS
area: main
in suites:
size: 145,388 kB
sloc: cpp: 335,976; ansic: 82,241; fortran: 20,963; objc: 9,402; sh: 8,756; yacc: 4,392; lex: 4,333; perl: 1,544; java: 1,366; awk: 1,259; makefile: 659; xml: 192
file content (5326 lines) | stat: -rw-r--r-- 162,246 bytes
parent folder | download | duplicates (2)
@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2025 The Octave Project Developers
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node System Utilities
@chapter System Utilities

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

@menu
* Timing Utilities::
* Filesystem Utilities::
* File Archiving Utilities::
* Networking Utilities::
* Controlling Subprocesses::
* Process ID Information::
* Environment Variables::
* Current Working Directory::
* Password Database Functions::
* Group Database Functions::
* System Information::
* Hashing Functions::
@end menu

@node Timing Utilities
@section 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:

@table @code
@item usec
Microseconds after the second (0-999999).

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

@item min
Minutes after the hour (0-59).

@item hour
Hours since midnight (0-23).

@item mday
Day of the month (1-31).

@item mon
Months since January (0-11).

@item year
Years since 1900.

@item wday
Days since Sunday (0-6).

@item yday
Days since January 1 (0-365).

@item isdst
Daylight saving time flag.

@item gmtoff
Seconds offset from UTC.

@item zone
Time zone.
@end table

@noindent
In the descriptions of the following functions, this structure is
referred to as a @var{tm_struct}.

@c time libinterp/corefcn/time.cc
@anchor{XREFtime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{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 @code{time} was 856163706.
@xseealso{@ref{XREFstrftime,,strftime}, @ref{XREFstrptime,,strptime}, @ref{XREFlocaltime,,localtime}, @ref{XREFgmtime,,gmtime}, @ref{XREFmktime,,mktime}, @ref{XREFnow,,now}, @ref{XREFdate,,date}, @ref{XREFclock,,clock}, @ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}, @ref{XREFdatevec,,datevec}, @ref{XREFcalendar,,calendar}, @ref{XREFweekday,,weekday}}
@end deftypefn


@c now scripts/time/now.m
@anchor{XREFnow}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {t =} now ()
Return the current local date/time as a serial day number
(@pxref{XREFdatenum,,@code{datenum}}).

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

The fractional part, @code{rem (now, 1)} corresponds to the current time.
@xseealso{@ref{XREFclock,,clock}, @ref{XREFdate,,date}, @ref{XREFdatenum,,datenum}}
@end deftypefn


@c ctime scripts/time/ctime.m
@anchor{XREFctime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} ctime (@var{t})
Convert a value returned from @code{time} (or any other non-negative
integer), to the local time and return a string of the same form as
@code{asctime}.

The function @code{ctime (time)} is equivalent to
@code{asctime (localtime (time))}.  For example:

@example
@group
ctime (time ())
   @result{} "Mon Feb 17 01:15:06 1997@backslashchar{}n"
@end group
@end example
@xseealso{@ref{XREFasctime,,asctime}, @ref{XREFtime,,time}, @ref{XREFlocaltime,,localtime}}
@end deftypefn


@c gmtime libinterp/corefcn/time.cc
@anchor{XREFgmtime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tm_struct} =} gmtime (@var{t})
Given a value returned from @code{time}, or any non-negative integer,
return a time structure corresponding to UTC (Coordinated Universal Time).

For example:

@example
@group
gmtime (time ())
     @result{} @{
           usec = 0
           sec = 6
           min = 15
           hour = 7
           mday = 17
           mon = 1
           year = 97
           wday = 1
           yday = 47
           isdst = 0
           gmtoff = 0
           zone = GMT
        @}
@end group
@end example
@xseealso{@ref{XREFstrftime,,strftime}, @ref{XREFstrptime,,strptime}, @ref{XREFlocaltime,,localtime}, @ref{XREFmktime,,mktime}, @ref{XREFtime,,time}, @ref{XREFnow,,now}, @ref{XREFdate,,date}, @ref{XREFclock,,clock}, @ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}, @ref{XREFdatevec,,datevec}, @ref{XREFcalendar,,calendar}, @ref{XREFweekday,,weekday}}
@end deftypefn


@c localtime libinterp/corefcn/time.cc
@anchor{XREFlocaltime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tm_struct} =} localtime (@var{t})
Given a value returned from @code{time}, or any non-negative integer,
return a time structure corresponding to the local time zone.

@example
@group
localtime (time ())
     @result{} @{
           usec = 0
           sec = 6
           min = 15
           hour = 1
           mday = 17
           mon = 1
           year = 97
           wday = 1
           yday = 47
           isdst = 0
           gmtoff = -21600
           zone = CST
        @}
@end group
@end example
@xseealso{@ref{XREFstrftime,,strftime}, @ref{XREFstrptime,,strptime}, @ref{XREFgmtime,,gmtime}, @ref{XREFmktime,,mktime}, @ref{XREFtime,,time}, @ref{XREFnow,,now}, @ref{XREFdate,,date}, @ref{XREFclock,,clock}, @ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}, @ref{XREFdatevec,,datevec}, @ref{XREFcalendar,,calendar}, @ref{XREFweekday,,weekday}}
@end deftypefn


@c mktime libinterp/corefcn/time.cc
@anchor{XREFmktime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{seconds} =} mktime (@var{tm_struct})
Convert a time structure corresponding to the local time to the number of
seconds since the epoch.

For example:

@example
@group
mktime (localtime (time ()))
     @result{} 856163706
@end group
@end example
@xseealso{@ref{XREFstrftime,,strftime}, @ref{XREFstrptime,,strptime}, @ref{XREFlocaltime,,localtime}, @ref{XREFgmtime,,gmtime}, @ref{XREFtime,,time}, @ref{XREFnow,,now}, @ref{XREFdate,,date}, @ref{XREFclock,,clock}, @ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}, @ref{XREFdatevec,,datevec}, @ref{XREFcalendar,,calendar}, @ref{XREFweekday,,weekday}}
@end deftypefn


@c asctime scripts/time/asctime.m
@anchor{XREFasctime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} asctime (@var{tm_struct})
Convert a time structure to a string using the following
format: @qcode{"ddd mmm mm HH:MM:SS yyyy@backslashchar{}n"}.

For example:

@example
@group
asctime (localtime (time ()))
     @result{} "Mon Feb 17 01:15:06 1997@backslashchar{}n"
@end group
@end example

This is equivalent to @code{ctime (time ())}.
@xseealso{@ref{XREFctime,,ctime}, @ref{XREFlocaltime,,localtime}, @ref{XREFtime,,time}}
@end deftypefn


@c strftime libinterp/corefcn/time.cc
@anchor{XREFstrftime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} strftime (@var{fmt}, @var{tm_struct})
Format the time structure @var{tm_struct} in a flexible way using the format
string @var{fmt} that contains @samp{%} substitutions similar to those in
@code{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 @samp{%} 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:

@example
@group
strftime ("%r (%Z) %A %e %B %Y", localtime (time ()))
      @result{} "01:15:06 AM (CST) Monday 17 February 1997"
@end group
@end example

Octave's @code{strftime} function supports a superset of the ANSI C field
specifiers.

@noindent
Literal character fields:

@table @code
@item %%
% character.

@item %n
Newline character.

@item %t
Tab character.
@end table

@noindent
Numeric modifiers (a nonstandard extension):

@table @code
@item - (dash)
Do not pad the field.

@item _ (underscore)
Pad the field with spaces.
@end table

@noindent
Time fields:

@table @code
@item %H
Hour (00-23).

@item %I
Hour (01-12).

@item %k
Hour (0-23).

@item %l
Hour (1-12).

@item %M
Minute (00-59).

@item %p
Locale's AM or PM.

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

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

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

@item %S
Second (00-61).

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

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

@item %z
Offset from UTC (±@nospell{hhmm}), or nothing if no time zone is
determinable.

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

@noindent
Date fields:

@table @code
@item %a
Locale's abbreviated weekday name (Sun-Sat).

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

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

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

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

@item %C
Century (00-99).

@item %d
Day of month (01-31).

@item %e
Day of month ( 1-31).

@item %D
Date (mm/dd/yy).

@item %h
Same as %b.

@item %j
Day of year (001-366).

@item %m
Month (01-12).

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

@item %w
Day of week (0-6).

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

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

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

@item %Y
Year (1970-).
@end table
@xseealso{@ref{XREFstrptime,,strptime}, @ref{XREFlocaltime,,localtime}, @ref{XREFgmtime,,gmtime}, @ref{XREFmktime,,mktime}, @ref{XREFtime,,time}, @ref{XREFnow,,now}, @ref{XREFdate,,date}, @ref{XREFclock,,clock}, @ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}, @ref{XREFdatevec,,datevec}, @ref{XREFcalendar,,calendar}, @ref{XREFweekday,,weekday}}
@end deftypefn


@c strptime libinterp/corefcn/time.cc
@anchor{XREFstrptime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{tm_struct}, @var{nchars}] =} strptime (@var{str}, @var{fmt})
Convert the string @var{str} to the time structure @var{tm_struct} under
the control of the format string @var{fmt}.

If @var{fmt} fails to match, @var{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.
@xseealso{@ref{XREFstrftime,,strftime}, @ref{XREFlocaltime,,localtime}, @ref{XREFgmtime,,gmtime}, @ref{XREFmktime,,mktime}, @ref{XREFtime,,time}, @ref{XREFnow,,now}, @ref{XREFdate,,date}, @ref{XREFclock,,clock}, @ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}, @ref{XREFdatevec,,datevec}, @ref{XREFcalendar,,calendar}, @ref{XREFweekday,,weekday}}
@end deftypefn


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

@c clock scripts/time/clock.m
@anchor{XREFclock}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{datevec} =} clock ()
@deftypefnx {} {[@var{datevec}, @var{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 @var{isdst} is true if Daylight Savings Time
(DST) is in effect for the system's time zone.

For example:

@example
@group
fix (clock ())
  @result{}   1993      8     20      4     56      1
@end group
@end example

@code{clock} is more accurate on systems that have the @code{gettimeofday}
function.
@xseealso{@ref{XREFnow,,now}, @ref{XREFdate,,date}, @ref{XREFdatevec,,datevec}}
@end deftypefn


@c date scripts/time/date.m
@anchor{XREFdate}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{str} =} date ()
Return the current date as a character string in the form DD-MMM-YYYY@.

For example:

@example
@group
date ()
  @result{} 20-Aug-1993
@end group
@end example
@xseealso{@ref{XREFnow,,now}, @ref{XREFclock,,clock}, @ref{XREFdatestr,,datestr}, @ref{XREFlocaltime,,localtime}}
@end deftypefn


@c etime scripts/time/etime.m
@anchor{XREFetime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{secs} =} etime (@var{t2}, @var{t1})
Return the difference in seconds between two time values returned from
@code{clock} (@math{@var{t2} - @var{t1}}).

For example:

@example
@group
t0 = clock ();
# many computations later@dots{}
elapsed_time = etime (clock (), t0);
@end group
@end example

@noindent
will set the variable @code{elapsed_time} to the number of seconds since the
variable @code{t0} was set.
@xseealso{@ref{XREFtic,,tic}, @ref{XREFtoc,,toc}, @ref{XREFclock,,clock}, @ref{XREFcputime,,cputime}, @ref{XREFaddtodate,,addtodate}}
@end deftypefn


@c cputime libinterp/corefcn/data.cc
@anchor{XREFcputime}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{total}, @var{user}, @var{system}] =} cputime ();
Return the CPU time used by your Octave session.

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

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

Note that because Octave used some CPU time to start, it is reasonable
to check to see if @code{cputime} works by checking to see if the total
CPU time used is nonzero.
@xseealso{@ref{XREFtic,,tic}, @ref{XREFtoc,,toc}}
@end deftypefn


@c is_leap_year scripts/time/is_leap_year.m
@anchor{XREFis_leap_year}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{tf} =} is_leap_year ()
@deftypefnx {} {@var{tf} =} is_leap_year (@var{year})
Return true if @var{year} is a leap year and false otherwise.

If no year is specified, @code{is_leap_year} uses the current year.

For example:

@example
@group
is_leap_year (2000)
   @result{} 1
@end group
@end example
@xseealso{@ref{XREFweekday,,weekday}, @ref{XREFeomday,,eomday}, @ref{XREFcalendar,,calendar}}
@end deftypefn


@c tic libinterp/corefcn/data.cc
@anchor{XREFtic}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} tic ()
@deftypefnx {} {@var{id} =} tic ()
Initialize a wall-clock timer.

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

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

Example 1 : benchmarking code with internal timer

@example
@group
tic;
# many computations later@dots{}
elapsed_time = toc;
@end group
@end example

Example 2 : mixed timer id and internal timer

@example
@group
tic;
pause (1);
toc
@result{} Elapsed time is 1.0089 seconds.
id = tic;
pause (2);
toc (id)
@result{} Elapsed time is 2.01142 seconds.
toc
Elapsed time is 3.02308 seconds.
@end group
@end example

@noindent
Calling @code{tic} and @code{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 @code{cputime} function instead.  The @code{tic} and @code{toc}
functions report the actual wall clock time that elapsed between the calls.
This may include time spent processing other jobs or doing nothing at all.
@xseealso{@ref{XREFtoc,,toc}, @ref{XREFcputime,,cputime}}
@end deftypefn


@c toc libinterp/corefcn/data.cc
@anchor{XREFtoc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} toc ()
@deftypefnx {} {} toc (@var{id})
@deftypefnx {} {@var{elapsed_time} =} toc (@dots{})
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 @code{tic}.

When given the identifier @var{id} of a specific timer, return the number of
seconds elapsed since the timer @var{id} was initialized.

@xref{XREFtic,,@code{tic}}, for examples of the use of @code{tic}/@code{toc}.

@xseealso{@ref{XREFtic,,tic}, @ref{XREFcputime,,cputime}}
@end deftypefn


@c pause libinterp/corefcn/sysdep.cc
@anchor{XREFpause}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} pause ()
@deftypefnx {} {} pause (@var{n})
@deftypefnx {} {@var{old_state} =} pause ("on")
@deftypefnx {} {@var{old_state} =} pause ("off")
@deftypefnx {} {@var{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 @var{n} is a positive real value, it indicates
the number of seconds the program shall be suspended, for example:

@example
@group
tic; pause (0.05); toc
     @print{} Elapsed time is 0.05039 seconds.
@end group
@end example

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

@example
@group
disp ("wait please...");
pause (5);
clc;
@end group
@end example

If invoked with a string argument @qcode{"on"}, @qcode{"off"}, or
@qcode{"query"}, the state of the pause function is changed or queried.  When
the state is @qcode{"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:

@example
@group
old_state = pause ("off");
tic; pause (0.05); toc
     @print{} Elapsed time is 3.00407e-05 seconds.
pause (old_state);
@end group
@end example

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

@xseealso{@ref{XREFkbhit,,kbhit}}
@end deftypefn


@c datenum scripts/time/datenum.m
@anchor{XREFdatenum}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{days} =} datenum (@var{datevec})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute})
@deftypefnx {} {@var{days} =} datenum (@var{year}, @var{month}, @var{day}, @var{hour}, @var{minute}, @var{second})
@deftypefnx {} {@var{days} =} datenum ("datestr")
@deftypefnx {} {@var{days} =} datenum ("datestr", @var{f})
@deftypefnx {} {@var{days} =} datenum ("datestr", @var{p})
@deftypefnx {} {[@var{days}, @var{secs}] =} datenum (@dots{})
Return the date/time input as a serial day number, with Jan 1, 0000
defined as day 1.

The integer part, @code{floor (@var{days})} counts the number of
complete days in the date input.

The fractional part, @code{rem (@var{days}, 1)} corresponds to the time
on the given day.

The input may be a date vector (@pxref{XREFdatevec,,@code{datevec}}),
date string (@pxref{XREFdatestr,,@code{datestr}}), or directly specified
as input.

When processing input datestrings, @var{f} is the format string used to
interpret date strings (@pxref{XREFdatestr,,@code{datestr}}).  If no
format @var{f} is specified, then a relatively slow search is performed
through various formats.  It is always preferable to specify the format
string @var{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 @var{year}, @var{month}, @var{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.

@var{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 @var{secs} holds the time on the specified day with
greater precision than @var{days}.

Notes:

@itemize
@item
Years can be negative and/or fractional.

@item
Months below 1 are considered to be January.

@item
Days of the month start at 1.

@item
Days beyond the end of the month go into subsequent months.

@item
Days before the beginning of the month go to the previous month.

@item
Days can be fractional.
@end itemize

Examples:

@example
@group
Convert from datestrs:
d = datenum ("1966-06-14")
@result{} d = 718232
@end group

@group
d = datenum (@{"1966-06-14", "1966-06-15", "1966-06-16"@})
@result{} d =
      718232
      718233
      718234
@end group

@group
Convert from datevec:
d = datenum ([1966 06 14])
@result{} d = 718232
@end group

@group
d = datenum ([1966 06 14 23 59 59])
@result{} d = 718232.9999884259
@end group

@group
Specify date components separately:
d = datenum (1966, 6, 14)
@result{} d = 718232
@end group

@group
d = datenum (1966, magic(3), 1)
@result{} d =

      718280   718068   718219
      718127   718188   718249
      718158   718311   718099
@end group
@end example

@strong{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 @code{datestr}, are nonexistent or ambiguous.

@strong{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.

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

@xseealso{@ref{XREFdatestr,,datestr}, @ref{XREFdatevec,,datevec}, @ref{XREFnow,,now}, @ref{XREFclock,,clock}, @ref{XREFdate,,date}}
@end deftypefn


@c datestr scripts/time/datestr.m
@anchor{XREFdatestr}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{str} =} datestr (@var{date})
@deftypefnx {} {@var{str} =} datestr (@var{date}, @var{f})
@deftypefnx {} {@var{str} =} datestr (@var{date}, @var{f}, @var{p})
Format the given date/time according to the format @var{f} and return
the result in @var{str}.

@var{date} is a serial date number (@pxref{XREFdatenum,,@code{datenum}}), a
date vector (@pxref{XREFdatevec,,@code{datevec}}), or a string or cell array
of strings.  In the latter case, it is passed to @code{datevec} to guess the
input date format.

@var{f} can be an integer which corresponds to one of the codes in the table
below, or a date format string.

@var{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:

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

If @var{f} is a format string, the following symbols are recognized:

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

If @var{f} is not specified or is @code{-1}, then use 0, 1 or 16, depending
on whether the date portion or the time portion of @var{date} is empty.

If @var{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.

@xseealso{@ref{XREFdatenum,,datenum}, @ref{XREFdatevec,,datevec}, @ref{XREFdate,,date}, @ref{XREFnow,,now}, @ref{XREFclock,,clock}}
@end deftypefn


@c datevec scripts/time/datevec.m
@anchor{XREFdatevec}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{v} =} datevec (@var{date})
@deftypefnx {} {@var{v} =} datevec (@var{date}, @var{f})
@deftypefnx {} {@var{v} =} datevec (@var{date}, @var{p})
@deftypefnx {} {@var{v} =} datevec (@var{date}, @var{f}, @var{p})
@deftypefnx {} {[@var{y}, @var{m}, @var{d}, @var{h}, @var{mi}, @var{s}] =} datevec (@dots{})
Convert a serial date number (@pxref{XREFdatenum,,@code{datenum}}) or date
string (@pxref{XREFdatestr,,@code{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.

@var{v} is a two-dimensional array of date vectors, one date vector per
row.  For array inputs, ordering of @var{v} is based on column major order
of dates in @var{data}.

@var{f} is the format string used to interpret date strings
(@pxref{XREFdatestr,,@code{datestr}}).  If @var{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 @var{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.

@var{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.
@xseealso{@ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}, @ref{XREFclock,,clock}, @ref{XREFnow,,now}, @ref{XREFdate,,date}}
@end deftypefn


@c addtodate scripts/time/addtodate.m
@anchor{XREFaddtodate}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{d} =} addtodate (@var{d}, @var{q}, @var{f})
Add @var{q} amount of time (with units @var{f}) to the serial datenum,
@var{d}.

@var{f} must be one of @qcode{"year"}, @qcode{"month"}, @qcode{"day"},
@qcode{"hour"}, @qcode{"minute"}, @qcode{"second"}, or
@qcode{"millisecond"}.
@xseealso{@ref{XREFdatenum,,datenum}, @ref{XREFdatevec,,datevec}, @ref{XREFetime,,etime}}
@end deftypefn


@c calendar scripts/time/calendar.m
@anchor{XREFcalendar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{c} =} calendar ()
@deftypefnx {} {@var{c} =} calendar (@var{d})
@deftypefnx {} {@var{c} =} calendar (@var{y}, @var{m})
@deftypefnx {} {} calendar (@dots{})
Return the current monthly calendar in a 6x7 matrix.

If @var{d} is specified, return the calendar for the month containing the
date @var{d}, which must be a serial date number or a date string.

If @var{y} and @var{m} are specified, return the calendar for year @var{y}
and month @var{m}.

If no output arguments are specified, print the calendar on the screen
instead of returning a matrix.
@xseealso{@ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}}
@end deftypefn


@c weekday scripts/time/weekday.m
@anchor{XREFweekday}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{n}, @var{s}] =} weekday (@var{d})
@deftypefnx {} {[@var{n}, @var{s}] =} weekday (@var{d}, @var{format})
Return the day of the week as a number in @var{n} and as a string in
@var{s}.

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

@var{d} is a serial date number or a date string.

If the string @var{format} is not present or is equal to @qcode{"short"}
then @var{s} will contain the abbreviated name of the weekday.  If
@var{format} is @qcode{"long"} then @var{s} will contain the full name.

Table of return values based on @var{format}:

@multitable @columnfractions .06 .13 .16
@headitem @var{n} @tab @qcode{"short"} @tab @qcode{"long"}
@item 1 @tab Sun @tab Sunday
@item 2 @tab Mon @tab Monday
@item 3 @tab Tue @tab Tuesday
@item 4 @tab Wed @tab Wednesday
@item 5 @tab Thu @tab Thursday
@item 6 @tab Fri @tab Friday
@item 7 @tab Sat @tab Saturday
@end multitable

@xseealso{@ref{XREFeomday,,eomday}, @ref{XREFis_leap_year,,is_leap_year}, @ref{XREFcalendar,,calendar}, @ref{XREFdatenum,,datenum}, @ref{XREFdatevec,,datevec}}
@end deftypefn


@c eomday scripts/time/eomday.m
@anchor{XREFeomday}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{e} =} eomday (@var{y}, @var{m})
Return the last day of the month @var{m} for the year @var{y}.
@xseealso{@ref{XREFweekday,,weekday}, @ref{XREFdatenum,,datenum}, @ref{XREFdatevec,,datevec}, @ref{XREFis_leap_year,,is_leap_year}, @ref{XREFcalendar,,calendar}}
@end deftypefn


@c datetick scripts/plot/appearance/datetick.m
@anchor{XREFdatetick}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} datetick ()
@deftypefnx {} {} datetick (@var{axis_str})
@deftypefnx {} {} datetick (@var{date_format})
@deftypefnx {} {} datetick (@var{axis_str}, @var{date_format})
@deftypefnx {} {} datetick (@dots{}, "keeplimits")
@deftypefnx {} {} datetick (@dots{}, "keepticks")
@deftypefnx {} {} datetick (@var{hax}, @dots{})
Add date-formatted tick labels to an axis.

The axis to apply the ticks to is determined by @var{axis_str} which can
take the values @qcode{"x"}, @qcode{"y"}, or @qcode{"z"}.  The default
value is @qcode{"x"}.

The formatting of the labels is determined by the variable
@var{date_format}, which can either be a string or positive integer that
@code{datestr} accepts.

If the first argument @var{hax} is an axes handle, then plot into this axes,
rather than the current axes returned by @code{gca}.

@xseealso{@ref{XREFdatenum,,datenum}, @ref{XREFdatestr,,datestr}}
@end deftypefn


@node Filesystem Utilities
@section 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.

@c movefile scripts/miscellaneous/movefile.m
@anchor{XREFmovefile}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} movefile @var{f1}
@deftypefnx {} {} movefile @var{f1} @var{f2}
@deftypefnx {} {} movefile @var{f1} @var{f2} f
@deftypefnx {} {} movefile (@var{f1})
@deftypefnx {} {} movefile (@var{f1}, @var{f2})
@deftypefnx {} {} movefile (@var{f1}, @var{f2}, 'f')
@deftypefnx {} {[@var{status}] =} movefile (@dots{})
@deftypefnx {} {[@var{status}, @var{msg}] =} movefile (@dots{})
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} movefile (@dots{})
Move the source file or directory @var{f1} to the destination @var{f2}.

The name @var{f1} may contain globbing patterns, or may be a cell array of
strings.  If @var{f1} expands to multiple filenames, @var{f2} must be a
directory.

If no destination @var{f2} is specified then the destination is the present
working directory.  If @var{f2} is a filename then @var{f1} is renamed to
@var{f2}.

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

If successful, @var{status} is logical 1, and @var{msg}, @var{msgid} are
empty character strings ("").  Otherwise, @var{status} is logical 0,
@var{msg} contains a system-dependent error message, and @var{msgid}
contains a unique message identifier.  Note that the status code is exactly
opposite that of the @code{system} command.
@xseealso{@ref{XREFrename,,rename}, @ref{XREFcopyfile,,copyfile}, @ref{XREFunlink,,unlink}, @ref{XREFdelete,,delete}, @ref{XREFglob,,glob}}
@end deftypefn


@c rename libinterp/corefcn/dirfns.cc
@anchor{XREFrename}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rename @var{old} @var{new}
@deftypefnx {} {[@var{status}, @var{msg}] =} rename (@var{old}, @var{new})
Change the name of file @var{old} to @var{new}.

If successful, @var{status} is 0 and @var{msg} is an empty string.
Otherwise, @var{status} is -1 and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFmovefile,,movefile}, @ref{XREFcopyfile,,copyfile}, @ref{XREFls,,ls}, @ref{XREFdir,,dir}}
@end deftypefn


@c copyfile scripts/miscellaneous/copyfile.m
@anchor{XREFcopyfile}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} copyfile @var{f1} @var{f2}
@deftypefnx {} {} copyfile @var{f1} @var{f2} f
@deftypefnx {} {} copyfile (@var{f1}, @var{f2})
@deftypefnx {} {} copyfile (@var{f1}, @var{f2}, 'f')
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} copyfile (@dots{})
Copy the source file(s) or directory @var{f1} to the destination @var{f2}.

The name @var{f1} may contain globbing patterns, or may be a cell array of
strings.  If @var{f1} expands to multiple filenames, @var{f2} must be a
directory.

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

If successful, @var{status} is logical 1, and @var{msg}, @var{msgid} are
empty character strings ("").  Otherwise, @var{status} is logical 0,
@var{msg} contains a system-dependent error message, and @var{msgid}
contains a unique message identifier.  Note that the status code is exactly
opposite that of the @code{system} command.
@xseealso{@ref{XREFmovefile,,movefile}, @ref{XREFrename,,rename}, @ref{XREFunlink,,unlink}, @ref{XREFdelete,,delete}, @ref{XREFglob,,glob}}
@end deftypefn


@c unlink libinterp/corefcn/syscalls.cc
@anchor{XREFunlink}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} unlink (@var{file})
@deftypefnx {} {[@var{status}, @var{msg}] =} unlink (@var{file})
Delete the file named @var{file}.

If successful, @var{status} is 0 and @var{msg} is an empty string.
Otherwise, @var{status} is -1 and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFdelete,,delete}, @ref{XREFrmdir,,rmdir}}
@end deftypefn


@c link libinterp/corefcn/dirfns.cc
@anchor{XREFlink}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} link @var{old} @var{new}
@deftypefnx {} {[@var{status}, @var{msg}] =} link (@var{old}, @var{new})
Create a new link (also known as a hard link) to an existing file.

If successful, @var{status} is 0 and @var{msg} is an empty string.
Otherwise, @var{status} is -1 and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFsymlink,,symlink}, @ref{XREFunlink,,unlink}, @ref{XREFreadlink,,readlink}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c symlink libinterp/corefcn/dirfns.cc
@anchor{XREFsymlink}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} symlink @var{old} @var{new}
@deftypefnx {} {[@var{status}, @var{msg}] =} symlink (@var{old}, @var{new})
Create a symbolic link @var{new} which contains the string @var{old}.

If successful, @var{status} is 0 and @var{msg} is an empty string.
Otherwise, @var{status} is -1 and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFlink,,link}, @ref{XREFunlink,,unlink}, @ref{XREFreadlink,,readlink}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c readlink libinterp/corefcn/dirfns.cc
@anchor{XREFreadlink}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{result} =} readlink @var{symlink}
@deftypefnx {} {[@var{result}, @var{err}, @var{msg}] =} readlink (@var{symlink})
Read the value of the symbolic link @var{symlink}.

If successful, @var{result} contains the contents of the symbolic link
@var{symlink}, @var{err} is 0, and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFlstat,,lstat}, @ref{XREFsymlink,,symlink}, @ref{XREFlink,,link}, @ref{XREFunlink,,unlink}, @ref{XREFdelete,,delete}}
@end deftypefn


@c mkdir scripts/miscellaneous/mkdir.m
@anchor{XREFmkdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} mkdir @var{dirname}
@deftypefnx {} {} mkdir @var{parent} @var{dirname}
@deftypefnx {} {} mkdir (@var{dirname})
@deftypefnx {} {} mkdir (@var{parent}, @var{dirname})
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} mkdir (@dots{})
Create a directory named @var{dirname} in the directory @var{parent},
creating any intermediate directories if necessary.

If @var{dirname} is a relative path, and no @var{parent} directory is
specified, then the present working directory is used.

If successful, @var{status} is logical 1, and @var{msg}, @var{msgid} are
empty character strings ("").  Otherwise, @var{status} is logical 0,
@var{msg} contains a system-dependent error message, and @var{msgid}
contains a unique message identifier.  Note that the status code is exactly
opposite that of the @code{system} command.

When creating a directory permissions will be set to
@w{@code{0777 - UMASK}}.

@xseealso{@ref{XREFrmdir,,rmdir}, @ref{XREFpwd,,pwd}, @ref{XREFcd,,cd}, @ref{XREFumask,,umask}}
@end deftypefn


@c rmdir libinterp/corefcn/dirfns.cc
@anchor{XREFrmdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} rmdir @var{dir}
@deftypefnx {} {} rmdir (@var{dir}, "s")
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} rmdir (@dots{})
Remove the directory named @var{dir}.

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

If successful, @var{status} is logical 1, and @var{msg}, @var{msgid} are empty
character strings ("").  Otherwise, @var{status} is logical 0, @var{msg}
contains a system-dependent error message, and @var{msgid} contains a unique
message identifier.

@xseealso{@ref{XREFmkdir,,mkdir}, @ref{XREFconfirm_recursive_rmdir,,confirm_recursive_rmdir}, @ref{XREFpwd,,pwd}}
@end deftypefn


@c confirm_recursive_rmdir libinterp/corefcn/dirfns.cc
@anchor{XREFconfirm_recursive_rmdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} confirm_recursive_rmdir ()
@deftypefnx {} {@var{old_val} =} confirm_recursive_rmdir (@var{new_val})
@deftypefnx {} {@var{old_val} =} confirm_recursive_rmdir (@var{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 @qcode{"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.
@xseealso{@ref{XREFrmdir,,rmdir}}
@end deftypefn


@c mkfifo libinterp/corefcn/syscalls.cc
@anchor{XREFmkfifo}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} mkfifo (@var{name}, @var{mode})
@deftypefnx {} {[@var{status}, @var{msg}] =} mkfifo (@var{name}, @var{mode})
Create a FIFO special file named @var{name} with file mode @var{mode}.

@var{mode} is interpreted as an octal number and is subject to umask
processing.  The final calculated mode is @code{@var{mode} - @var{umask}}.

If successful, @var{status} is 0 and @var{msg} is an empty string.
Otherwise, @var{status} is -1 and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFpipe,,pipe}, @ref{XREFumask,,umask}}
@end deftypefn


@c umask libinterp/corefcn/file-io.cc
@anchor{XREFumask}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{oldmask} =} umask (@var{mask})
Set the permission mask for file creation.

The parameter @var{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 @var{mode} which are
modified according to the octal value of @var{mask}.  The final permissions
for the new object are @code{@var{mode} - @var{mask}}.
@xseealso{@ref{XREFfopen,,fopen}, @ref{XREFmkdir,,mkdir}, @ref{XREFmkfifo,,mkfifo}}
@end deftypefn


@anchor{XREFlstat}
@c stat libinterp/corefcn/syscalls.cc
@anchor{XREFstat}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file})
@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{fid})
@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file})
@deftypefnx {} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{fid})
Return a structure @var{info} containing the following information about
@var{file} or file identifier @var{fid}.

@table @code
@item dev
ID of device containing a directory entry for this file.

@item ino
File number of the file.

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

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

@item nlink
Number of links.

@item uid
User ID of file's owner.

@item gid
Group ID of file's group.

@item rdev
ID of device for block or character special files.

@item size
Size in bytes.

@item atime
Time of last access in the same form as time values returned from
@code{time}.  @xref{Timing Utilities}.

@item mtime
Time of last modification in the same form as time values returned from
@code{time}.  @xref{Timing Utilities}.

@item ctime
Time of last file status change in the same form as time values
returned from @code{time}.  @xref{Timing Utilities}.

@item blksize
Size of blocks in the file.

@item blocks
Number of blocks allocated for file.
@end table

If the call is successful @var{err} is 0 and @var{msg} is an empty string.
If the file does not exist, or some other error occurs, @var{info} is an
empty matrix, @var{err} is @minus{}1, and @var{msg} contains the
corresponding system error message.

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

For example:

@example
[info, err, msg] = stat ("/vmlinuz")
  @result{} 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
     @}
  @result{} err = 0
  @result{} msg =
@end example
@xseealso{@ref{XREFlstat,,lstat}, @ref{XREFls,,ls}, @ref{XREFdir,,dir}, @ref{XREFisfile,,isfile}, @ref{XREFisfolder,,isfolder}}
@end deftypefn


@c S_ISBLK libinterp/corefcn/syscalls.cc
@anchor{XREFS_ISBLK}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} S_ISBLK (@var{mode})
Return true if @var{mode} corresponds to a block device.

The value of @var{mode} is assumed to be returned from a call to
@code{stat}.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c S_ISCHR libinterp/corefcn/syscalls.cc
@anchor{XREFS_ISCHR}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} S_ISCHR (@var{mode})
Return true if @var{mode} corresponds to a character device.

The value of @var{mode} is assumed to be returned from a call to
@code{stat}.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c S_ISDIR libinterp/corefcn/syscalls.cc
@anchor{XREFS_ISDIR}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} S_ISDIR (@var{mode})
Return true if @var{mode} corresponds to a directory.

The value of @var{mode} is assumed to be returned from a call to
@code{stat}.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c S_ISFIFO libinterp/corefcn/syscalls.cc
@anchor{XREFS_ISFIFO}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} S_ISFIFO (@var{mode})
Return true if @var{mode} corresponds to a fifo.

The value of @var{mode} is assumed to be returned from a call to
@code{stat}.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c S_ISLNK libinterp/corefcn/syscalls.cc
@anchor{XREFS_ISLNK}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} S_ISLNK (@var{mode})
Return true if @var{mode} corresponds to a symbolic link.

The value of @var{mode} is assumed to be returned from a call to
@code{stat}.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c S_ISREG libinterp/corefcn/syscalls.cc
@anchor{XREFS_ISREG}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} S_ISREG (@var{mode})
Return true if @var{mode} corresponds to a regular file.

The value of @var{mode} is assumed to be returned from a call to
@code{stat}.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c S_ISSOCK libinterp/corefcn/syscalls.cc
@anchor{XREFS_ISSOCK}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} S_ISSOCK (@var{mode})
Return true if @var{mode} corresponds to a socket.

The value of @var{mode} is assumed to be returned from a call to
@code{stat}.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c fileattrib scripts/miscellaneous/fileattrib.m
@anchor{XREFfileattrib}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} fileattrib
@deftypefnx {} {} fileattrib @var{file}
@deftypefnx {} {} fileattrib (@var{file})
@deftypefnx {} {[@var{status}, @var{attrib}] =} fileattrib (@dots{})
@deftypefnx {} {[@var{status}, @var{msg}, @var{msgid}] =} fileattrib (@dots{})
Report attribute information about @var{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:

@table @code
@item Name
Full name of @var{file}.

@item archive
True if @var{file} is an archive (Windows).

@item system
True if @var{file} is a system file (Windows).

@item hidden
True if @var{file} is a hidden file (Windows).

@item directory
True if @var{file} is a directory.

@item  UserRead
@itemx GroupRead
@itemx OtherRead
True if the user (group; other users) has read permission for @var{file}.

@item  UserWrite
@itemx GroupWrite
@itemx OtherWrite
True if the user (group; other users) has write permission for @var{file}.

@item  UserExecute
@itemx GroupExecute
@itemx OtherExecute
True if the user (group; other users) has execute permission for @var{file}.
@end table

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

If @var{file} contains globbing characters, information about all matching
files is returned in a structure array.

If outputs are requested, the first is @var{status} which takes the value 1
when the operation was successful, and 0 otherwise.  The second output
contains the structure described above (@var{attrib}) if the operation was
successful; otherwise, the second output is a system-dependent error message
(@var{msg}).  The third output is an empty string ("") when the operation
was successful, or a unique message identifier (@var{msgid}) in the case of
failure.
@xseealso{@ref{XREFstat,,stat}, @ref{XREFglob,,glob}}
@end deftypefn


@c isfile scripts/miscellaneous/isfile.m
@anchor{XREFisfile}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isfile (@var{f})
Return true if @var{f} is a regular file and false otherwise.

If @var{f} is a cell array of strings, @var{tf} is a logical array of the
same size.
@xseealso{@ref{XREFisfolder,,isfolder}, @ref{XREFexist,,exist}, @ref{XREFstat,,stat}, @ref{XREFis_absolute_filename,,is_absolute_filename}, @ref{XREFis_rooted_relative_filename,,is_rooted_relative_filename}}
@end deftypefn


@c isdir scripts/legacy/isdir.m
@anchor{XREFisdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isdir (@var{f})

This function is not recommended.  Use @code{isfolder} or
@code{file_in_loadpath} instead.

Return true if @var{f} is a directory and false otherwise.

Compatibility Note: The @sc{matlab} function of the same name will also
search for @var{f} in the load path directories.  To emulate this behavior
use

@example
@var{tf} = ! isempty (file_in_loadpath (@var{f}))
@end example

@xseealso{@ref{XREFisfolder,,isfolder}, @ref{XREFfile_in_loadpath,,file_in_loadpath}, @ref{XREFexist,,exist}, @ref{XREFstat,,stat}, @ref{XREFis_absolute_filename,,is_absolute_filename}, @ref{XREFis_rooted_relative_filename,,is_rooted_relative_filename}}
@end deftypefn


@c isfolder scripts/miscellaneous/isfolder.m
@anchor{XREFisfolder}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isfolder (@var{f})
Return true if @var{f} is a directory and false otherwise.

If @var{f} is a cell array of strings, @var{tf} is a logical array of the
same size.
@xseealso{@ref{XREFisfile,,isfile}, @ref{XREFexist,,exist}, @ref{XREFstat,,stat}, @ref{XREFis_absolute_filename,,is_absolute_filename}, @ref{XREFis_rooted_relative_filename,,is_rooted_relative_filename}}
@end deftypefn


@c readdir libinterp/corefcn/dirfns.cc
@anchor{XREFreaddir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{files} =} readdir (@var{dir})
@deftypefnx {} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir})
Return the names of files in the directory @var{dir} as a cell array of
strings.

If an error occurs, return an empty cell array in @var{files}.
If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFls,,ls}, @ref{XREFdir,,dir}, @ref{XREFglob,,glob}, @ref{XREFwhat,,what}}
@end deftypefn


@c glob libinterp/corefcn/dirfns.cc
@anchor{XREFglob}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{cstr} =} glob (@var{pattern})
Given an array of pattern strings (as a char array or a cell array) in
@var{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

@table @code
@item *
matches any string, including the null string,

@item ?
matches any single character, and

@item [@dots{}]
matches any of the enclosed characters.
@end table

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

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

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

@xseealso{@ref{XREFls,,ls}, @ref{XREFdir,,dir}, @ref{XREFreaddir,,readdir}, @ref{XREFwhat,,what}}
@end deftypefn


@c file_in_path libinterp/corefcn/utils.cc
@anchor{XREFfile_in_path}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{fname} =} file_in_path (@var{path}, @var{file})
@deftypefnx {} {@var{fname} =} file_in_path (@var{path}, @var{file}, "all")
Return the absolute name of @var{file} if it can be found in @var{path}.

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

@example
@group
file_in_path (EXEC_PATH, "sh")
     @result{} "/bin/sh"
@end group
@end example

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 @qcode{"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.
@xseealso{@ref{XREFfile_in_loadpath,,file_in_loadpath}, @ref{XREFdir_in_loadpath,,dir_in_loadpath}, @ref{XREFpath,,path}}
@end deftypefn


@c filesep libinterp/corefcn/dirfns.cc
@anchor{XREFfilesep}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{sep} =} filesep ()
@deftypefnx {} {} filesep ("all")
Return the system-dependent character used to separate directory names.

If @qcode{"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 @samp{/} (forward slash) under UNIX or @w{Mac OS X}, @samp{/} and
@samp{\} (forward and backward slashes) under Windows.
@xseealso{@ref{XREFpathsep,,pathsep}}
@end deftypefn


@c fileparts scripts/miscellaneous/fileparts.m
@anchor{XREFfileparts}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{dir}, @var{name}, @var{ext}] =} fileparts (@var{filename})
Return the directory, name, and extension components of @var{filename}.

The input @var{filename} is a string which is parsed.  There is no attempt
to check whether the filename or directory specified actually exists.
@xseealso{@ref{XREFfullfile,,fullfile}, @ref{XREFfilesep,,filesep}}
@end deftypefn


@c fullfile scripts/miscellaneous/fullfile.m
@anchor{XREFfullfile}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{filename} =} fullfile (@var{dir1}, @var{dir2}, @dots{}, @var{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.:

@example
@group
fullfile ("/home/username", "data", @{"f1.csv", "f2.csv", "f3.csv"@})
  @result{}
      @{
        [1,1] = /home/username/data/f1.csv
        [1,2] = /home/username/data/f2.csv
        [1,3] = /home/username/data/f3.csv
      @}
@end group
@end example

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: @code{fullfile} does not perform any validation of the resulting full
filename.
@xseealso{@ref{XREFfileparts,,fileparts}, @ref{XREFfilesep,,filesep}}
@end deftypefn


@c tilde_expand libinterp/corefcn/sysdep.cc
@anchor{XREFtilde_expand}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{newstr} =} tilde_expand (@var{string})
@deftypefnx {} {@var{newcstr} =} tilde_expand (@var{cellstr})
Perform tilde expansion on @var{string}.

If @var{string} begins with a tilde character, (@samp{~}), all of the
characters preceding the first slash (or all characters, if there is no
slash) are treated as a possible user name, and the tilde and the following
characters up to the slash are replaced by the home directory of the named
user.  If the tilde is followed immediately by a slash, the tilde is
replaced by the home directory of the user running Octave.

If the input is a cell array of strings @var{cellstr} then tilde expansion
is performed on each string element.

Examples:

@example
@group
tilde_expand ("~joeuser/bin")
     @result{} "/home/joeuser/bin"
tilde_expand ("~/bin")
     @result{} "/home/jwe/bin"
@end group
@end example
@end deftypefn


@c canonicalize_file_name libinterp/corefcn/syscalls.cc
@anchor{XREFcanonicalize_file_name}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{cname}, @var{status}, @var{msg}] =} canonicalize_file_name (@var{fname})
Return the canonical name of file @var{fname}.

If the file does not exist the empty string ("") is returned.  No tilde
expansion of @var{fname} is performed.
@xseealso{@ref{XREFmake_absolute_filename,,make_absolute_filename}, @ref{XREFis_absolute_filename,,is_absolute_filename}, @ref{XREFis_rooted_relative_filename,,is_rooted_relative_filename}, @ref{XREFis_same_file,,is_same_file}, @ref{XREFtilde_expand,,tilde_expand}}
@end deftypefn


@c make_absolute_filename libinterp/corefcn/utils.cc
@anchor{XREFmake_absolute_filename}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{abs_fname} =} make_absolute_filename (@var{file})
Return the full name of @var{file} beginning from the root of the file system.

No check is done for the existence of @var{file}.  No tilde expansion of
@var{file} is performed.
@xseealso{@ref{XREFcanonicalize_file_name,,canonicalize_file_name}, @ref{XREFis_absolute_filename,,is_absolute_filename}, @ref{XREFis_rooted_relative_filename,,is_rooted_relative_filename}, @ref{XREFisfolder,,isfolder}, @ref{XREFtilde_expand,,tilde_expand}}
@end deftypefn


@c is_absolute_filename libinterp/corefcn/utils.cc
@anchor{XREFis_absolute_filename}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} is_absolute_filename (@var{file})
Return true if @var{file} is an absolute filename.
@xseealso{@ref{XREFis_rooted_relative_filename,,is_rooted_relative_filename}, @ref{XREFmake_absolute_filename,,make_absolute_filename}, @ref{XREFisfolder,,isfolder}}
@end deftypefn


@c is_same_file libinterp/corefcn/utils.cc
@anchor{XREFis_same_file}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{same} =} is_same_file (@var{filepath1}, @var{filepath2})
Return true if @var{filepath1} and @var{filepath2} refer to the same file.

If either @var{filepath1} or @var{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 (@file{file1} vs.@: @file {FILE1}),
file separator (@samp{\} vs.@: @samp{/}), and format (@file{A~spaces.txt} (8.3
convention) vs.@: @file{A filename with spaces.txt}).  This function returns
true if the paths in @var{filepath1} and @var{filepath2} actually refer to the
same file or folder, and false otherwise.

Note that unlike @code{strcmp}, this function requires that @var{filepath1}
and @var{filepath2} exist, as well as point to the same location, in order to
return true.

@xseealso{@ref{XREFcanonicalize_file_name,,canonicalize_file_name}, @ref{XREFstrcmp,,strcmp}}
@end deftypefn


@c is_rooted_relative_filename libinterp/corefcn/utils.cc
@anchor{XREFis_rooted_relative_filename}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} is_rooted_relative_filename (@var{file})
Return true if @var{file} is a rooted-relative filename.
@xseealso{@ref{XREFis_absolute_filename,,is_absolute_filename}, @ref{XREFmake_absolute_filename,,make_absolute_filename}, @ref{XREFisfolder,,isfolder}}
@end deftypefn


@c recycle scripts/miscellaneous/recycle.m
@anchor{XREFrecycle}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} recycle ()
@deftypefnx {} {@var{old_val} =} recycle (@var{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 @sc{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.
@xseealso{@ref{XREFdelete,,delete}, @ref{XREFrmdir,,rmdir}}
@end deftypefn


@node File Archiving Utilities
@section File Archiving Utilities

@c bunzip2 scripts/miscellaneous/bunzip2.m
@anchor{XREFbunzip2}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} bunzip2 (@var{bzfile})
@deftypefnx {} {} bunzip2 (@var{bzfile}, @var{dir})
@deftypefnx {} {@var{filelist} =} bunzip2 (@dots{})
Unpack the bzip2 archive @var{bzfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the one where @var{bzfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{@ref{XREFbzip2,,bzip2}, @ref{XREFunpack,,unpack}, @ref{XREFgunzip,,gunzip}, @ref{XREFunzip,,unzip}, @ref{XREFuntar,,untar}}
@end deftypefn


@c gzip libinterp/dldfcn/gzip.cc
@anchor{XREFgzip}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{filelist} =} gzip (@var{files})
@deftypefnx {} {@var{filelist} =} gzip (@var{files}, @var{dir})
Compress the list of files and directories specified in @var{files}.

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

If @var{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 @var{dir} which may
lead to files overwriting each other if there are multiple files with the
same name.

If @var{dir} does not exist it is created.

The optional output @var{filelist} is a list of the compressed files.
@xseealso{@ref{XREFgunzip,,gunzip}, @ref{XREFunpack,,unpack}, @ref{XREFbzip2,,bzip2}, @ref{XREFzip,,zip}, @ref{XREFtar,,tar}}
@end deftypefn


@c gunzip scripts/miscellaneous/gunzip.m
@anchor{XREFgunzip}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} gunzip (@var{gzfile})
@deftypefnx {} {} gunzip (@var{gzfile}, @var{outdir})
@deftypefnx {} {@var{filelist} =} gunzip (@dots{})
Unpack the gzip archive @var{gzfile}.

If @var{gzfile} is a directory, all gzfiles in the directory will be
recursively unpacked.

If @var{outdir} is specified the files are unpacked in this directory rather
than the one where @var{gzfile} is located.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{@ref{XREFgzip,,gzip}, @ref{XREFunpack,,unpack}, @ref{XREFbunzip2,,bunzip2}, @ref{XREFunzip,,unzip}, @ref{XREFuntar,,untar}}
@end deftypefn


@c tar scripts/miscellaneous/tar.m
@anchor{XREFtar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{filelist} =} tar (@var{tarfile}, @var{files})
@deftypefnx {} {@var{filelist} =} tar (@var{tarfile}, @var{files}, @var{rootdir})
Pack the list of files and directories specified in @var{files} into the
TAR archive @var{tarfile}.

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

If @var{rootdir} is defined then any files without absolute pathnames are
located relative to @var{rootdir} rather than the current directory.

The optional output @var{filelist} is a list of the files that were included
in the archive.
@xseealso{@ref{XREFuntar,,untar}, @ref{XREFunpack,,unpack}, @ref{XREFbzip2,,bzip2}, @ref{XREFgzip,,gzip}, @ref{XREFzip,,zip}}
@end deftypefn


@c untar scripts/miscellaneous/untar.m
@anchor{XREFuntar}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} untar (@var{tarfile})
@deftypefnx {} {} untar (@var{tarfile}, @var{dir})
@deftypefnx {} {@var{filelist} =} untar (@dots{})
Unpack the TAR archive @var{tarfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the current directory.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{@ref{XREFtar,,tar}, @ref{XREFunpack,,unpack}, @ref{XREFbunzip2,,bunzip2}, @ref{XREFgunzip,,gunzip}, @ref{XREFunzip,,unzip}}
@end deftypefn


@c zip scripts/miscellaneous/zip.m
@anchor{XREFzip}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{filelist} =} zip (@var{zipfile}, @var{files})
@deftypefnx {} {@var{filelist} =} zip (@var{zipfile}, @var{files}, @var{rootdir})
Compress the list of files and directories specified in @var{files} into the
ZIP archive @var{zipfile}.

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

If @var{rootdir} is defined then any files without absolute pathnames are
located relative to @var{rootdir} rather than the current directory.

The optional output @var{filelist} is a list of the files that were included
in the archive.
@xseealso{@ref{XREFunzip,,unzip}, @ref{XREFunpack,,unpack}, @ref{XREFbzip2,,bzip2}, @ref{XREFgzip,,gzip}, @ref{XREFtar,,tar}}
@end deftypefn


@c unzip scripts/miscellaneous/unzip.m
@anchor{XREFunzip}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} unzip (@var{zipfile})
@deftypefnx {} {} unzip (@var{zipfile}, @var{dir})
@deftypefnx {} {@var{filelist} =} unzip (@dots{})
Unpack the ZIP archive @var{zipfile}.

If @var{dir} is specified the files are unpacked in this directory rather
than the current directory.

The optional output @var{filelist} is a list of the uncompressed files.
@xseealso{@ref{XREFzip,,zip}, @ref{XREFunpack,,unpack}, @ref{XREFbunzip2,,bunzip2}, @ref{XREFgunzip,,gunzip}, @ref{XREFuntar,,untar}}
@end deftypefn


@c unpack scripts/miscellaneous/unpack.m
@anchor{XREFunpack}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{files} =} unpack (@var{file})
@deftypefnx {} {@var{files} =} unpack (@var{file}, @var{dir})
@deftypefnx {} {@var{files} =} unpack (@var{file}, @var{dir}, @var{filetype})
Unpack the archive @var{file} based on its extension to the directory
@var{dir}.

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

If @var{dir} is not specified or is empty (@code{[]}), it defaults to the
current directory.  If a directory is in the file list, then @var{filetype}
must also be specified.

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

Valid filetype extensions:

@table @code
@item  @nospell{bz}
@itemx @nospell{bz2}
bzip archive

@item @nospell{gz}
gzip archive

@item tar
tar archive

@item  tarbz
@itemx tarbz2
@itemx tbz
@itemx tbz2
tar + bzip archive

@item  targz
@itemx tgz
tar + gzip archive

@item z
compress archive

@item zip
zip archive
@end table

The optional return value is a list of @var{files} unpacked.
@xseealso{@ref{XREFbunzip2,,bunzip2}, @ref{XREFgunzip,,gunzip}, @ref{XREFunzip,,unzip}, @ref{XREFuntar,,untar}, @ref{XREFbzip2,,bzip2}, @ref{XREFgzip,,gzip}, @ref{XREFzip,,zip}, @ref{XREFtar,,tar}}
@end deftypefn


@c bzip2 libinterp/dldfcn/gzip.cc
@anchor{XREFbzip2}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{filelist} =} bzip2 (@var{files})
@deftypefnx {} {@var{filelist} =} bzip2 (@var{files}, @var{dir})
Compress the list of files specified in @var{files}.

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

If @var{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 @var{dir} which may
lead to files overwriting each other if there are multiple files with the
same name.

If @var{dir} does not exist it is created.

The optional output @var{filelist} is a list of the compressed files.
@xseealso{@ref{XREFbunzip2,,bunzip2}, @ref{XREFunpack,,unpack}, @ref{XREFgzip,,gzip}, @ref{XREFzip,,zip}, @ref{XREFtar,,tar}}
@end deftypefn


@node Networking Utilities
@section Networking Utilities

@menu
* FTP Objects::
* WWW Access::
* Base64 and Binary Data Transmission::
@end menu

@c gethostname libinterp/corefcn/syscalls.cc
@anchor{XREFgethostname}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{name} =} gethostname ()
Return the hostname of the system where Octave is running.
@end deftypefn


@node FTP Objects
@subsection FTP Objects

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

@c @ftp/ftp scripts/@ftp/ftp.m
@anchor{XREF@@ftp/ftp}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{f} =} ftp (@var{host})
@deftypefnx {} {@var{f} =} ftp (@var{host}, @var{username}, @var{password})
Connect to the FTP server @var{host} with @var{username} and @var{password}.

If @var{username} and @var{password} are not specified, user
@qcode{"anonymous"} with no password is used.  The returned FTP object
@var{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.

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

@xseealso{@ref{XREF@@ftp/ascii,,@@ftp/ascii}, @ref{XREF@@ftp/binary,,@@ftp/binary}, @ref{XREF@@ftp/cd,,@@ftp/cd}, @ref{XREF@@ftp/close,,@@ftp/close}, @ref{XREF@@ftp/delete,,@@ftp/delete}, @ref{XREF@@ftp/dir,,@@ftp/dir}, @ref{XREF@@ftp/mget,,@@ftp/mget}, @ref{XREF@@ftp/mkdir,,@@ftp/mkdir}, @ref{XREF@@ftp/mput,,@@ftp/mput}, @ref{XREF@@ftp/rename,,@@ftp/rename}, @ref{XREF@@ftp/rmdir,,@@ftp/rmdir}}
@end deftypefn


@c @ftp/close scripts/@ftp/close.m
@anchor{XREF@@ftp/close}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} close (@var{f})
Close the FTP connection represented by the FTP object @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@xseealso{@ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/mget scripts/@ftp/mget.m
@anchor{XREF@@ftp/mget}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} mget (@var{f}, @var{file})
@deftypefnx {} {} mget (@var{f}, @var{dir})
@deftypefnx {} {} mget (@var{f}, @var{remote_name}, @var{target})
Download a remote file @var{file} or directory @var{dir} to the local
directory on the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

The arguments @var{file} and @var{dir} can include wildcards and any
files or directories on the remote server that match will be downloaded.

If a third string argument @var{target} is given, then it must indicate
the path to the local destination directory.  @var{target} may be a
relative or absolute path.
@xseealso{@ref{XREF@@ftp/mput,,@@ftp/mput}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/mput scripts/@ftp/mput.m
@anchor{XREF@@ftp/mput}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} mput (@var{f}, @var{file})
@deftypefnx {} {@var{file_list} =} mput (@var{f}, @var{file})
Upload the local file @var{file} into the current remote directory on the
FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

The argument @var{file} is passed through the @code{glob} function and any
files that match the wildcards in @var{file} will be uploaded.

The optional output argument @var{file_list} contains a cell array of
strings with the names of the uploaded files.
@xseealso{@ref{XREF@@ftp/mget,,@@ftp/mget}, @ref{XREF@@ftp/mkdir,,@@ftp/mkdir}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/cd scripts/@ftp/cd.m
@anchor{XREF@@ftp/cd}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{cwd} =} cd (@var{f})
@deftypefnx {} {} cd (@var{f}, @var{path})
@deftypefnx {} {@var{new_cwd} =} cd (@var{f}, @var{path})
Get or set the remote directory on the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

If @var{path} is not specified, return the remote current working
directory.  Otherwise, set the remote directory to @var{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.
@xseealso{@ref{XREF@@ftp/dir,,@@ftp/dir}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/dir scripts/@ftp/dir.m
@anchor{XREF@@ftp/dir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dir (@var{f})
@deftypefnx {} {@var{lst} =} dir (@var{f})
List the current directory in verbose form for the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.

If the optional output @var{lst} is requested return a struct array
with one entry per file with the fields @code{name}, @code{date},
@code{bytes}, @code{isdir}, @code{datenum}.
@xseealso{@ref{XREF@@ftp/cd,,@@ftp/cd}, @ref{XREF@@ftp/mkdir,,@@ftp/mkdir}, @ref{XREF@@ftp/rmdir,,@@ftp/rmdir}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/ascii scripts/@ftp/ascii.m
@anchor{XREF@@ftp/ascii}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} ascii (@var{f})
Set the FTP connection @var{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.

@var{f} is an FTP object returned by the @code{ftp} function.
@xseealso{@ref{XREF@@ftp/binary,,@@ftp/binary}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/binary scripts/@ftp/binary.m
@anchor{XREF@@ftp/binary}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} binary (@var{f})
Set the FTP connection @var{f} to use binary mode for transfers.

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

@var{f} is an FTP object returned by the @code{ftp} function.
@xseealso{@ref{XREF@@ftp/ascii,,@@ftp/ascii}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/delete scripts/@ftp/delete.m
@anchor{XREF@@ftp/delete}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} delete (@var{f}, @var{file})
Delete the remote file @var{file} over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@xseealso{@ref{XREF@@ftp/rmdir,,@@ftp/rmdir}, @ref{XREF@@ftp/rename,,@@ftp/rename}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/rename scripts/@ftp/rename.m
@anchor{XREF@@ftp/rename}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} rename (@var{f}, @var{oldname}, @var{newname})
Rename or move the remote file or directory @var{oldname} to @var{newname},
over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@xseealso{@ref{XREF@@ftp/delete,,@@ftp/delete}, @ref{XREF@@ftp/rmdir,,@@ftp/rmdir}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/mkdir scripts/@ftp/mkdir.m
@anchor{XREF@@ftp/mkdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} mkdir (@var{f}, @var{path})
Create the remote directory @var{path}, over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@xseealso{@ref{XREF@@ftp/rmdir,,@@ftp/rmdir}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@c @ftp/rmdir scripts/@ftp/rmdir.m
@anchor{XREF@@ftp/rmdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {} rmdir (@var{f}, @var{path})
Remove the remote directory @var{path}, over the FTP connection @var{f}.

@var{f} is an FTP object returned by the @code{ftp} function.
@xseealso{@ref{XREF@@ftp/delete,,@@ftp/delete}, @ref{XREF@@ftp/mkdir,,@@ftp/mkdir}, @ref{XREF@@ftp/rename,,@@ftp/rename}, @ref{XREF@@ftp/ftp,,@@ftp/ftp}}
@end deftypefn


@node WWW Access
@subsection WWW Access

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

@c web scripts/web/web.m
@anchor{XREFweb}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{status} =} web ()
@deftypefnx {} {@var{status} =} web (@var{url})
@deftypefnx {} {@var{status} =} web (@var{url}, @var{option})
@deftypefnx {} {@var{status} =} web (@var{url}, @var{option_1}, @dots{}, @var{option_N})
@deftypefnx {} {[@var{status}, @var{h}, @var{url}] =} web (@dots{})

Open @var{url} in the default system web browser.

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

Additional options can be passed for @sc{matlab} compatibility, but are
ignored.

@itemize @bullet
@item
@samp{-browser} Open @var{url} in the default system browser.

@item
@samp{-new} No effect on the system browser.

@item
@samp{-noaddressbox} No effect on the system browser.

@item
@samp{-notoolbar} No effect on the system browser.

@end itemize

The return value @var{status} has one of the values:

@itemize @bullet
@item
@samp{0} Found and opened system browser successfully.

@item
@samp{1} Cannot find the system browser.

@item
@samp{2} System browser found, but an error occurred.

@end itemize

The return values @var{handle} and @var{url} are currently unimplemented
but given for compatibility.

@xseealso{@ref{XREFweboptions,,weboptions}, @ref{XREFwebread,,webread}, @ref{XREFwebwrite,,webwrite}, @ref{XREFurlread,,urlread}, @ref{XREFurlwrite,,urlwrite}}
@end deftypefn


@c urlread libinterp/corefcn/urlwrite.cc
@anchor{XREFurlread}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{s} =} urlread (@var{url})
@deftypefnx {} {[@var{s}, @var{success}] =} urlread (@var{url})
@deftypefnx {} {[@var{s}, @var{success}, @var{message}] =} urlread (@var{url})
@deftypefnx {} {[@dots{}] =} urlread (@var{url}, @var{method}, @var{param})
Download a remote file specified by its @var{url} and return its content
in string @var{s}.

For example:

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

The variable @var{success} is 1 if the download was successful,
otherwise it is 0 in which case @var{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:

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

GET and POST requests can be specified by @var{method} and @var{param}.
The parameter @var{method} is either @samp{get} or @samp{post} and
@var{param} is a cell array of parameter and value pairs.
For example:

@example
@group
s = urlread ("http://www.google.com/search",
             "get", @{"query", "octave"@});
@end group
@end example
@xseealso{@ref{XREFurlwrite,,urlwrite}}
@end deftypefn


@c urlwrite libinterp/corefcn/urlwrite.cc
@anchor{XREFurlwrite}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} urlwrite (@var{url}, @var{localfile})
@deftypefnx {} {@var{f} =} urlwrite (@var{url}, @var{localfile})
@deftypefnx {} {[@var{f}, @var{success}] =} urlwrite (@var{url}, @var{localfile})
@deftypefnx {} {[@var{f}, @var{success}, @var{message}] =} urlwrite (@var{url}, @var{localfile})
Download a remote file specified by its @var{url} and save it as
@var{localfile}.

For example:

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

The full path of the downloaded file is returned in @var{f}.

The variable @var{success} is 1 if the download was successful,
otherwise it is 0 in which case @var{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:

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

GET and POST requests can be specified by @var{method} and @var{param}.
The parameter @var{method} is either @samp{get} or @samp{post} and
@var{param} is a cell array of parameter and value pairs.
For example:

@example
@group
urlwrite ("http://www.google.com/search", "search.html",
          "get", @{"query", "octave"@});
@end group
@end example
@xseealso{@ref{XREFurlread,,urlread}}
@end deftypefn


@c webread scripts/web/webread.m
@anchor{XREFwebread}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{response} =} webread (@var{url})
@deftypefnx {} {@var{response} =} webread (@var{url}, @var{name1}, @var{value1}, @dots{})
@deftypefnx {} {@var{response} =} webread (@dots{}, @var{options})

Read content from RESTful web service.

Read content from the web service specified by @var{url} and return the
content in @var{response}.

All key-value pairs given (@var{name1}, @var{value1}, @dots{}) are appended
as query parameters to @var{url}.  To place a query in the body of the
message, use @code{webwrite}.  The web service defines the acceptable query
parameters.

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

@xseealso{@ref{XREFweboptions,,weboptions}, @ref{XREFwebwrite,,webwrite}}
@end deftypefn


@c webwrite scripts/web/webwrite.m
@anchor{XREFwebwrite}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{response} =} webwrite (@var{url}, @var{name1}, @var{value1}, @dots{})
@deftypefnx {} {@var{response} =} webwrite (@var{url}, @var{data})
@deftypefnx {} {@var{response} =} webwrite (@dots{}, @var{options})

Write data to RESTful web services.

Write content to the web service specified by @var{url} and return the
response in @var{response}.

All key-value pairs given (@var{name1}, @var{value1}, @dots{}) are added
as pairs of query parameters to the body of request method (@code{get},
@code{post}, @code{put}, etc.).

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

@xseealso{@ref{XREFweboptions,,weboptions}, @ref{XREFwebread,,webread}}
@end deftypefn


@c weboptions scripts/web/weboptions.m
@anchor{XREFweboptions}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{output} =} weboptions ()
@deftypefnx {} {@var{output} =} weboptions (@var{name1}, @var{value1}, @dots{})

Specify parameters for RESTful web services.

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

Multiple name and value pair arguments may be specified in any order as
@var{name1}, @var{value1}, @var{name2}, @var{value2}, etc.

The option names must match @strong{exactly} one of those specified in the
table below.

The following options are available:

@itemize @bullet
@item
@samp{CharacterEncoding} --- Specify the character encoding of the data:

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

@item
@samp{UserAgent} --- Specify the User Agent for the connection.

Default value is @samp{GNU Octave/version}, where @samp{version} is the
current version of Octave as returned by @code{version}.

@item
@samp{Timeout} --- Specify the timeout value for the connection in
seconds.

Default is 10 seconds.  @samp{Inf} is not currently supported.

@item
@samp{Username} --- User identifier for a basic HTTP connection.

Default is NULL@.  It must be a string.

@item
@samp{Password} --- User authentication password for HTTP connection.

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

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

@item
@samp{KeyValue} --- Specify the value of the key @samp{KeyName}.

@samp{KeyName} must be present in order to assign to this field.

@item
@samp{@nospell{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.
@code{@nospell{HeaderFields}@{i,1@}} is the name of a field and
@code{@nospell{HeaderFields}@{i,2@}} is its value.

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

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

@item
@samp{ContentType} --- Specify the content type of the data.

The following values are available:
@samp{auto}, @samp{text}, @samp{json}

Default is @samp{auto}.  It automatically determines the content type.
All other formats like @samp{audio}, @samp{binary}, etc.@: available in
@sc{matlab} are not currently supported.

@item
@samp{ContentReader} --- Not yet implemented.  Only for @sc{matlab}
compatibility.

@item
@samp{MediaType} --- Not yet implemented.  Only for @sc{matlab}
compatibility.

@item
@samp{RequestMethod} --- Specifies the type of request to be made.

The following methods are available:
@samp{get}, @samp{put}, @samp{post}, @samp{delete}, @samp{patch}

@code{webread} uses the HTTP GET method.  @code{webwrite} uses the HTTP
POST method as default.

@item
@samp{ArrayFormat} -- Not yet implemented.  Only for @sc{matlab}
compatibility.

@item
@samp{CertificateFilename} --- Not yet implemented.  Only for @sc{matlab}
compatibility.
@end itemize

@xseealso{@ref{XREFwebread,,webread}, @ref{XREFwebwrite,,webwrite}}
@end deftypefn


@node Base64 and Binary Data Transmission
@subsection 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.

@c base64_encode libinterp/corefcn/data.cc
@anchor{XREFbase64_encode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{s} =} base64_encode (@var{x})
Encode a double matrix or array @var{x} into the base64 format string
@var{s}.

@xseealso{@ref{XREFbase64_decode,,base64_decode}, @ref{XREFmatlab_net_base64decode,,matlab.net.base64decode}, @ref{XREFmatlab_net_base64encode,,matlab.net.base64encode}}
@end deftypefn


@c base64_decode libinterp/corefcn/data.cc
@anchor{XREFbase64_decode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{x} =} base64_decode (@var{s})
@deftypefnx {} {@var{x} =} base64_decode (@var{s}, @var{dims})
Decode the double matrix or array @var{x} from the base64 encoded string
@var{s}.

The optional input parameter @var{dims} should be a vector containing the
dimensions of the decoded array.
@xseealso{@ref{XREFbase64_encode,,base64_encode}, @ref{XREFmatlab_net_base64decode,,matlab.net.base64decode}, @ref{XREFmatlab_net_base64encode,,matlab.net.base64encode}}
@end deftypefn


@c matlab.net.base64encode scripts/+matlab/+net/base64encode.m
@anchor{XREFmatlab_net_base64encode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{b64_str} =} matlab.net.base64encode (@var{in})

Convert @var{in} to a base64 encoded string @var{b64_str}.

The input @var{in} can be a string or numeric vector.
The output @var{b64_str} will be encoded according to RFC 4648.

@xseealso{@ref{XREFmatlab_net_base64decode,,matlab.net.base64decode}, @ref{XREFbase64_decode,,base64_decode}, @ref{XREFbase64_encode,,base64_encode}, @ref{XREFunicode2native,,unicode2native}}
@end deftypefn


@c matlab.net.base64decode scripts/+matlab/+net/base64decode.m
@anchor{XREFmatlab_net_base64decode}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{out_vec} =} matlab.net.base64decode (@var{b64_str})

Convert base64 encoded @var{b64_str} to uint8 vector @var{out_vec}.

The input @var{b64_str} must be a string vector.
The output @var{out_vec} will be a uint8 vector that is decoded
according to RFC 4648.

@xseealso{@ref{XREFmatlab_net_base64encode,,matlab.net.base64encode}, @ref{XREFbase64_decode,,base64_decode}, @ref{XREFbase64_encode,,base64_encode}, @ref{XREFnative2unicode,,native2unicode}}
@end deftypefn


@node Controlling Subprocesses
@section Controlling Subprocesses

Octave includes some high-level commands like @code{system} and
@code{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.

@c system libinterp/corefcn/toplev.cc
@anchor{XREFsystem}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} system ("@var{string}")
@deftypefnx {} {} system ("@var{string}", @var{return_output})
@deftypefnx {} {} system ("@var{string}", @var{return_output}, @var{type})
@deftypefnx {} {[@var{status}, @var{output}] =} system (@dots{})
Execute a shell command specified by @var{string}.

If @var{system} is called with one or more output arguments, or if the optional
argument @var{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
@code{system} through the pager, use a command like

@example
@group
[~, text] = system ("cmd");
more on;
disp (text);
@end group
@end example

@noindent
or

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

If the optional argument @var{type} is @qcode{"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 @var{type} argument is omitted, it defaults to the value
@qcode{"sync"}.

The @code{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,

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

@noindent
will set the variable @var{output} to the string @samp{foo}, and the variable
@var{status} to the integer @samp{2}.

For commands run asynchronously, @var{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 @file{/bin/sh} for UNIX systems and @nospell{@file{cmd.exe}} for
Windows systems.
@xseealso{@ref{XREFunix,,unix}, @ref{XREFdos,,dos}}
@end deftypefn


@c unix scripts/miscellaneous/unix.m
@anchor{XREFunix}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} unix ("@var{command}")
@deftypefnx {} {@var{status} =} unix ("@var{command}")
@deftypefnx {} {[@var{status}, @var{text}] =} unix ("@var{command}")
@deftypefnx {} {[@dots{}] =} unix ("@var{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 @var{status} and any output in @var{text}.

When called with no output argument, or the @qcode{"-echo"} argument is
given, then @var{text} is also sent to standard output.
@xseealso{@ref{XREFdos,,dos}, @ref{XREFsystem,,system}, @ref{XREFisunix,,isunix}, @ref{XREFismac,,ismac}, @ref{XREFispc,,ispc}}
@end deftypefn


@c dos scripts/miscellaneous/dos.m
@anchor{XREFdos}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dos ("@var{command}")
@deftypefnx {} {@var{status} =} dos ("@var{command}")
@deftypefnx {} {[@var{status}, @var{text}] =} dos ("@var{command"})
@deftypefnx {} {[@dots{}] =} dos ("@var{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 @var{status} and any output in @var{text}.

When called with no output argument, or the @qcode{"-echo"} argument is
given, then @var{text} is also sent to standard output.
@xseealso{@ref{XREFunix,,unix}, @ref{XREFsystem,,system}, @ref{XREFisunix,,isunix}, @ref{XREFismac,,ismac}, @ref{XREFispc,,ispc}}
@end deftypefn


@c open scripts/miscellaneous/open.m
@anchor{XREFopen}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} open @var{file}
@deftypefnx {} {@var{output} =} open (@var{file})
Open the file @var{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

@table @code
@item .m
Open file in the editor.  No @var{output} value is returned.

@item  .mat
@itemx octave-workspace
Open the data file with @code{load}.  If no return value @var{output}
is requested, variables are loaded in the base workspace.  Otherwise
@var{output} will be a structure containing loaded data.
@xref{XREFload,,load function}.

@item .ofig
Open the figure with @code{hgload}.
@xref{XREFhgload,,hgload function}.

@item .fig, .ofig
Load the figure

@item .exe
Execute the program (on Windows systems only).  No @var{output} value
is returned.
@end table

Custom file extensions may also be handled if a function @code{openxxx},
where @code{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
@nospell{@qcode{".dat"}} data files in the base workspace, as is done by
default for @qcode{".mat"} files, one may define
@nospell{@qcode{"opendat.m"}} with the following contents:

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

Other file types are opened in the appropriate external application.
@end deftypefn


@c perl scripts/miscellaneous/perl.m
@anchor{XREFperl}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{output} =} perl (@var{scriptfile})
@deftypefnx {} {@var{output} =} perl (@var{scriptfile}, @var{argument1}, @var{argument2}, @dots{})
@deftypefnx {} {[@var{output}, @var{status}] =} perl (@dots{})
Invoke Perl script @var{scriptfile}, possibly with a list of command line
arguments.

Return output in @var{output} and optional status in @var{status}.  If
@var{scriptfile} is not an absolute filename it is searched for in the
current directory and then in the Octave loadpath.
@xseealso{@ref{XREFsystem,,system}, @ref{XREFpython,,python}}
@end deftypefn


@c python scripts/miscellaneous/python.m
@anchor{XREFpython}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{output} =} python (@var{scriptfile})
@deftypefnx {} {@var{output} =} python (@var{scriptfile}, @var{argument1}, @var{argument2}, @dots{})
@deftypefnx {} {[@var{output}, @var{status}] =} python (@dots{})
Invoke Python script @var{scriptfile}, possibly with a list of command line
arguments.

Return output in @var{output} and optional status in @var{status}.  If
@var{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
@command{python3} and on Windows by @command{python}.  You can override
these defaults by setting the @env{PYTHON} environment variable, for example
from within Octave using @code{setenv PYTHON /usr/local/bin/python3}.

@xseealso{@ref{XREFsystem,,system}, @ref{XREFperl,,perl}}
@end deftypefn


@c popen libinterp/corefcn/file-io.cc
@anchor{XREFpopen}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{fid} =} popen (@var{command}, @var{mode})
Start a process and create a pipe.

The name of the command to run is given by @var{command}.  The argument
@var{mode} may be

@table @asis
@item @qcode{"r"}
The pipe will be connected to the standard output of the process, and
open for reading.

@item @qcode{"w"}
The pipe will be connected to the standard input of the process, and
open for writing.
@end table

The file identifier corresponding to the input or output stream of the
process is returned in @var{fid}.

For example:

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

   @print{} drwxr-xr-x  33 root  root  3072 Feb 15 13:28 etc
   @print{} drwxr-xr-x   3 root  root  1024 Feb 15 13:28 lib
   @print{} drwxrwxrwt  15 root  root  2048 Feb 17 14:53 tmp
@end group
@end example
@xseealso{@ref{XREFpopen2,,popen2}}
@end deftypefn


@c pclose libinterp/corefcn/file-io.cc
@anchor{XREFpclose}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{status} =} pclose (@var{fid})
Close a file identifier @var{fid} that was opened by @code{popen}.

If successful, @code{fclose} returns 0, otherwise, it returns -1.

Programming Note: The function @code{fclose} may also be used for the same
purpose.
@xseealso{@ref{XREFfclose,,fclose}, @ref{XREFpopen,,popen}}
@end deftypefn


@c popen2 libinterp/corefcn/syscalls.cc
@anchor{XREFpopen2}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args})
Start a subprocess with two-way communication.

The name of the process is given by @var{command}, and @var{args} is an
array 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 @var{in} and @var{out}.  If execution of the command is
successful, @var{pid} contains the process ID of the subprocess.  Otherwise,
@var{pid} is @minus{}1.

For example:

@example
[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);

   @print{} these
   @print{} strings
   @print{} some
   @print{} are
@end example

Note that @code{popen2}, unlike @code{popen}, will not @nospell{"reap"}
the child process.  If you don't use @code{waitpid} to check the child's
exit status, it will linger until Octave exits.
@xseealso{@ref{XREFpopen,,popen}, @ref{XREFwaitpid,,waitpid}}
@end deftypefn


@c EXEC_PATH libinterp/corefcn/environment.cc
@anchor{XREFEXEC_PATH}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} EXEC_PATH ()
@deftypefnx {} {@var{old_val} =} EXEC_PATH (@var{new_val})
@deftypefnx {} {@var{old_val} =} EXEC_PATH (@var{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
@w{@env{OCTAVE_EXEC_PATH}}, but that value can be overridden by the command
line argument @option{--exec-path PATH}.

When called from inside a function with the @qcode{"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.

@xseealso{@ref{XREFIMAGE_PATH,,IMAGE_PATH}, @ref{XREFOCTAVE_HOME,,OCTAVE_HOME}, @ref{XREFOCTAVE_EXEC_HOME,,OCTAVE_EXEC_HOME}}
@end deftypefn


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

@c fork libinterp/corefcn/syscalls.cc
@anchor{XREFfork}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{pid}, @var{msg}] =} fork ()
Create a copy of the current process.

Fork can return one of the following values:

@table @asis
@item > 0
You are in the parent process.  The value returned from @code{fork} is the
process id of the child process.  You should probably arrange to wait for
any child processes to exit.

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

@item < 0
The call to @code{fork} failed for some reason.  You must take evasive
action.  A system dependent error message will be waiting in @var{msg}.
@end table
@end deftypefn


@c exec libinterp/corefcn/syscalls.cc
@anchor{XREFexec}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args})
Replace current process with a new process.

Calling @code{exec} without first calling @code{fork} will terminate your
current Octave process and replace it with the program named by @var{file}.
For example,

@example
exec ("ls", "-l")
@end example

@noindent
will run @code{ls} and return you to your shell prompt.

If successful, @code{exec} does not return.  If @code{exec} does return,
@var{err} will be nonzero, and @var{msg} will contain a system-dependent
error message.
@end deftypefn


@c pipe libinterp/corefcn/syscalls.cc
@anchor{XREFpipe}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{read_fd}, @var{write_fd}, @var{err}, @var{msg}] =} pipe ()
Create a pipe and return the reading and writing ends of the pipe into
@var{read_fd} and @var{write_fd} respectively.

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFmkfifo,,mkfifo}}
@end deftypefn


@c dup2 libinterp/corefcn/syscalls.cc
@anchor{XREFdup2}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{fid}, @var{msg}] =} dup2 (@var{old}, @var{new})
Duplicate a file descriptor.

If successful, @var{fid} is greater than zero and contains the new file ID@.
Otherwise, @var{fid} is negative and @var{msg} contains a system-dependent
error message.
@xseealso{@ref{XREFfopen,,fopen}, @ref{XREFfclose,,fclose}, @ref{XREFfcntl,,fcntl}}
@end deftypefn


@c waitpid libinterp/corefcn/syscalls.cc
@anchor{XREFwaitpid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{pid}, @var{status}, @var{msg}] =} waitpid (@var{pid}, @var{options})
Wait for process @var{pid} to terminate.

The @var{pid} argument can be:

@table @asis
@item @minus{}1
Wait for any child process.

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

@item > 0
Wait for termination of the child process with ID @var{pid}.
@end table

The @var{options} argument can be a bitwise OR of zero or more of the
following constants:

@table @code
@item 0
Wait until signal is received or a child process exits (this is the default
if the @var{options} argument is missing).

@item WNOHANG
Do not hang if status is not immediately available.

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

@item WCONTINUE
Return if a stopped child has been resumed by delivery of @code{SIGCONT}.
This value may not be meaningful on all systems.
@end table

If the returned value of @var{pid} is greater than 0, it is the process ID
of the child process that exited.  If an error occurs, @var{pid} will be
less than zero and @var{msg} will contain a system-dependent error message.
The value of @var{status} contains additional system-dependent information
about the subprocess that exited.
@xseealso{@ref{XREFWCONTINUE,,WCONTINUE}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWNOHANG,,WNOHANG}, @ref{XREFWSTOPSIG,,WSTOPSIG}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWUNTRACED,,WUNTRACED}}
@end deftypefn


@c WCONTINUE libinterp/corefcn/syscalls.cc
@anchor{XREFWCONTINUE}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{v} =} WCONTINUE ()
Return the numerical value of the @code{WCONTINUE} macro.

@code{WCONTINUE} is the option argument that may be passed to
@code{waitpid} to indicate that it should also return if a stopped child
has been resumed by delivery of a @code{SIGCONT} signal.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWNOHANG,,WNOHANG}, @ref{XREFWUNTRACED,,WUNTRACED}}
@end deftypefn


@c WCOREDUMP libinterp/corefcn/syscalls.cc
@anchor{XREFWCOREDUMP}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WCOREDUMP (@var{status})
Given @var{status} from a call to @code{waitpid}, return
true if the child produced a core dump.

This function should only be employed if @code{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., @nospell{AIX, SunOS}).
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWIFEXITED,,WIFEXITED}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWSTOPSIG,,WSTOPSIG}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}}
@end deftypefn


@c WEXITSTATUS libinterp/corefcn/syscalls.cc
@anchor{XREFWEXITSTATUS}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WEXITSTATUS (@var{status})
Given @var{status} from a call to @code{waitpid}, return
the exit status of the child.

This function should only be employed if @code{WIFEXITED} returned true.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWIFEXITED,,WIFEXITED}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWSTOPSIG,,WSTOPSIG}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}}
@end deftypefn


@c WIFCONTINUED libinterp/corefcn/syscalls.cc
@anchor{XREFWIFCONTINUED}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WIFCONTINUED (@var{status})
Given @var{status} from a call to @code{waitpid}, return
true if the child process was resumed by delivery of @code{SIGCONT}.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWIFEXITED,,WIFEXITED}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWSTOPSIG,,WSTOPSIG}}
@end deftypefn


@c WIFSIGNALED libinterp/corefcn/syscalls.cc
@anchor{XREFWIFSIGNALED}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WIFSIGNALED (@var{status})
Given @var{status} from a call to @code{waitpid}, return
true if the child process was terminated by a signal.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWIFEXITED,,WIFEXITED}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWSTOPSIG,,WSTOPSIG}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}}
@end deftypefn


@c WIFSTOPPED libinterp/corefcn/syscalls.cc
@anchor{XREFWIFSTOPPED}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WIFSTOPPED (@var{status})
Given @var{status} from a call to @code{waitpid}, return
true if the child process was stopped by delivery of a signal.

This is only possible if the call was done using @code{WUNTRACED} or when
the child is being traced (see ptrace(2)).
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWIFEXITED,,WIFEXITED}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWSTOPSIG,,WSTOPSIG}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}}
@end deftypefn


@c WIFEXITED libinterp/corefcn/syscalls.cc
@anchor{XREFWIFEXITED}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WIFEXITED (@var{status})
Given @var{status} from a call to @code{waitpid}, return
true if the child terminated normally.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWSTOPSIG,,WSTOPSIG}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}}
@end deftypefn


@c WNOHANG libinterp/corefcn/syscalls.cc
@anchor{XREFWNOHANG}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{v} =} WNOHANG ()
Return the numerical value of the @code{WNOHANG} macro.

@code{WNOHANG} is the option argument that may be passed to
@code{waitpid} to indicate that it should return its status immediately
instead of waiting for a process to exit.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWUNTRACED,,WUNTRACED}, @ref{XREFWCONTINUE,,WCONTINUE}}
@end deftypefn


@c WSTOPSIG libinterp/corefcn/syscalls.cc
@anchor{XREFWSTOPSIG}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WSTOPSIG (@var{status})
Given @var{status} from a call to @code{waitpid}, return
the number of the signal which caused the child to stop.

This function should only be employed if @code{WIFSTOPPED} returned true.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWIFEXITED,,WIFEXITED}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWTERMSIG,,WTERMSIG}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}}
@end deftypefn


@c WTERMSIG libinterp/corefcn/syscalls.cc
@anchor{XREFWTERMSIG}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} WTERMSIG (@var{status})
Given @var{status} from a call to @code{waitpid}, return
the number of the signal that caused the child process to terminate.

This function should only be employed if @code{WIFSIGNALED} returned true.
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWIFEXITED,,WIFEXITED}, @ref{XREFWEXITSTATUS,,WEXITSTATUS}, @ref{XREFWIFSIGNALED,,WIFSIGNALED}, @ref{XREFWCOREDUMP,,WCOREDUMP}, @ref{XREFWIFSTOPPED,,WIFSTOPPED}, @ref{XREFWSTOPSIG,,WSTOPSIG}, @ref{XREFWIFCONTINUED,,WIFCONTINUED}}
@end deftypefn


@c WUNTRACED libinterp/corefcn/syscalls.cc
@anchor{XREFWUNTRACED}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{v} =} WUNTRACED ()
Return the numerical value of the @code{WUNTRACED} macro.

@code{WUNTRACED} is the option argument that may be passed to
@code{waitpid} to indicate that it should also return if the child
process has stopped but is not traced via the @code{ptrace} system call
@xseealso{@ref{XREFwaitpid,,waitpid}, @ref{XREFWNOHANG,,WNOHANG}, @ref{XREFWCONTINUE,,WCONTINUE}}
@end deftypefn


@c fcntl libinterp/corefcn/syscalls.cc
@anchor{XREFfcntl}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} fcntl (@var{fid}, @var{request}, @var{arg})
@deftypefnx {} {[@var{status}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg})
Change the properties of the open file @var{fid}.

The following values may be passed as @var{request}:

@vtable @code
@item F_DUPFD
Return a duplicate file descriptor.

@item F_GETFD
Return the file descriptor flags for @var{fid}.

@item F_SETFD
Set the file descriptor flags for @var{fid}.

@item F_GETFL
Return the file status flags for @var{fid}.  The following codes may be
returned (some of the flags may be undefined on some systems).

@vtable @code
@item O_RDONLY
Open for reading only.

@item O_WRONLY
Open for writing only.

@item O_RDWR
Open for reading and writing.

@item O_APPEND
Append on each write.

@item O_CREAT
Create the file if it does not exist.

@item O_NONBLOCK
Non-blocking mode.

@item O_SYNC
Wait for writes to complete.

@item O_ASYNC
Asynchronous I/O.
@end vtable

@item F_SETFL
Set the file status flags for @var{fid} to the value specified by @var{arg}.
The only flags that can be changed are @w{@code{O_APPEND}}@ and
@w{@code{O_NONBLOCK}}.
@end vtable

If successful, @var{status} is 0 and @var{msg} is an empty string.  Otherwise,
@var{status} is -1 and @var{msg} contains a system-dependent error
message.
@xseealso{@ref{XREFfopen,,fopen}, @ref{XREFdup2,,dup2}}
@end deftypefn


@c kill libinterp/corefcn/syscalls.cc
@anchor{XREFkill}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} kill (@var{pid}, @var{sig})
@deftypefnx {} {[@var{status}, @var{msg}] =} kill (@var{pid}, @var{sig})
Send signal @var{sig} to process @var{pid}.

If @var{pid} is positive, then signal @var{sig} is sent to @var{pid}.

If @var{pid} is 0, then signal @var{sig} is sent to every process in the
process group of the current process.

If @var{pid} is -1, then signal @var{sig} is sent to every process except
process 1.

If @var{pid} is less than -1, then signal @var{sig} is sent to every process in
the process group @var{-pid}.

If @var{sig} is 0, then no signal is sent, but error checking is still
performed.

If successful, @var{status} is 0 and @var{msg} is an empty string.
Otherwise, @var{status} is -1 and @var{msg} contains a system-dependent
error message.
@end deftypefn


@c SIG libinterp/corefcn/sighandlers.cc
@anchor{XREFSIG}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{S} =} SIG ()
Return a structure containing Unix signal names and their defined values.
@end deftypefn


@node Process ID Information
@section Process, Group, and User IDs

@c getpgrp libinterp/corefcn/syscalls.cc
@anchor{XREFgetpgrp}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {pgid =} getpgrp ()
Return the process group id of the current process.
@end deftypefn


@c getpid libinterp/corefcn/syscalls.cc
@anchor{XREFgetpid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {pid =} getpid ()
Return the process id of the current process.
@xseealso{@ref{XREFgetppid,,getppid}}
@end deftypefn


@c getppid libinterp/corefcn/syscalls.cc
@anchor{XREFgetppid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {pid =} getppid ()
Return the process id of the parent process.
@xseealso{@ref{XREFgetpid,,getpid}}
@end deftypefn


@c geteuid libinterp/corefcn/syscalls.cc
@anchor{XREFgeteuid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {euid =} geteuid ()
Return the effective user id of the current process.
@xseealso{@ref{XREFgetuid,,getuid}}
@end deftypefn


@c getuid libinterp/corefcn/syscalls.cc
@anchor{XREFgetuid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {uid =} getuid ()
Return the real user id of the current process.
@xseealso{@ref{XREFgeteuid,,geteuid}}
@end deftypefn


@c getegid libinterp/corefcn/syscalls.cc
@anchor{XREFgetegid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {egid =} getegid ()
Return the effective group id of the current process.
@xseealso{@ref{XREFgetgid,,getgid}}
@end deftypefn


@c getgid libinterp/corefcn/syscalls.cc
@anchor{XREFgetgid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {gid =} getgid ()
Return the real group id of the current process.
@xseealso{@ref{XREFgetegid,,getegid}}
@end deftypefn


@node Environment Variables
@section Environment Variables

@c getenv libinterp/corefcn/sysdep.cc
@anchor{XREFgetenv}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{val} =} getenv ("@var{var}")
Return the value of the environment variable @var{var}.

For example,

@example
getenv ("PATH")
@end example

@noindent
returns a string containing the value of your path.
@xseealso{@ref{XREFsetenv,,setenv}, @ref{XREFunsetenv,,unsetenv}, @ref{XREFisenv,,isenv}}
@end deftypefn


@c isenv libinterp/corefcn/sysdep.cc
@anchor{XREFisenv}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isenv (@var{var})
Return true if the variable @var{var} is an environment variable, and false
otherwise.

For example,

@example
tf = isenv ("PATH")
@end example

@noindent
will typically return true on UNIX systems because @qcode{"PATH"} is an
environment variable for UNIX.
@xseealso{@ref{XREFgetenv,,getenv}, @ref{XREFsetenv,,setenv}, @ref{XREFunsetenv,,unsetenv}}
@end deftypefn


@c setenv libinterp/corefcn/sysdep.cc
@anchor{XREFsetenv}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} setenv ("@var{var}", @var{value})
@deftypefnx {} {} setenv (@var{var})
@deftypefnx {} {} putenv (@dots{})
Set the value of the environment variable @var{var} to @var{value}.

If no @var{value} is specified then the variable will be assigned the null
string.

Programming Note: @code{putenv} is an alias for @code{setenv} and can be used
interchangeably.
@xseealso{@ref{XREFunsetenv,,unsetenv}, @ref{XREFgetenv,,getenv}, @ref{XREFisenv,,isenv}}
@end deftypefn


@c unsetenv libinterp/corefcn/sysdep.cc
@anchor{XREFunsetenv}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} unsetenv ("@var{var}")
@deftypefnx {} {@var{status} =} unsetenv ("@var{var}")
Delete the environment variable @var{var}.

Return 0 if the variable was deleted, or did not exist, and -1 if an error
occurred.
@xseealso{@ref{XREFsetenv,,setenv}, @ref{XREFgetenv,,getenv}, @ref{XREFisenv,,isenv}}
@end deftypefn


@c get_home_directory libinterp/corefcn/sysdep.cc
@anchor{XREFget_home_directory}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{homedir} =} get_home_directory ()
Return the current home directory.

On most systems, this is equivalent to @code{getenv ("HOME")}.  On Windows
systems, if the environment variable @env{HOME} is not set then it is
equivalent to
@code{fullfile (getenv ("HOMEDRIVE"), getenv ("HOMEPATH"))}
@xseealso{@ref{XREFgetenv,,getenv}}
@end deftypefn


@node Current Working Directory
@section Current Working Directory

@c cd libinterp/corefcn/dirfns.cc
@anchor{XREFcd}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} cd @var{dir}
@deftypefnx {} {} cd
@deftypefnx {} {@var{old_dir} =} cd
@deftypefnx {} {@var{old_dir} =} cd (@var{dir})
@deftypefnx {} {} chdir @dots{}
Change the current working directory to @var{dir}.

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

For example,

@example
cd ~/octave
@end example

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

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

Compatibility Note: When called with no arguments, @sc{matlab} prints the
present working directory rather than changing to the user's home directory.
@xseealso{@ref{XREFpwd,,pwd}, @ref{XREFmkdir,,mkdir}, @ref{XREFrmdir,,rmdir}, @ref{XREFdir,,dir}, @ref{XREFls,,ls}}
@end deftypefn


@c ls scripts/miscellaneous/ls.m
@anchor{XREFls}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ls
@deftypefnx {} {} ls @var{filenames}
@deftypefnx {} {} ls @var{options}
@deftypefnx {} {} ls @var{options} @var{filenames}
@deftypefnx {} {@var{list} =} ls (@dots{})

List directory contents.

The @code{ls} function forwards to the @code{ls} command if it is available.
It falls back to calling the native operating system's directory listing
command.  Available @var{options} may vary from system to system.

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

If the optional output @var{list} is requested then @code{ls} returns a
character array with one row for each file/directory name.

Example usage on a UNIX-like system:

@example
@group
ls -l
     @print{} total 12
     @print{} -rw-r--r--   1 jwe  users  4488 Aug 19 04:02 foo.m
     @print{} -rw-r--r--   1 jwe  users  1315 Aug 17 23:14 bar.m
@end group
@end example

@xseealso{@ref{XREFdir,,dir}, @ref{XREFreaddir,,readdir}, @ref{XREFglob,,glob}, @ref{XREFwhat,,what}, @ref{XREFstat,,stat}, @ref{XREFfilesep,,filesep}, @ref{XREFls_command,,ls_command}}
@end deftypefn


@c ls_command scripts/miscellaneous/ls_command.m
@anchor{XREFls_command}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} ls_command ()
@deftypefnx {} {@var{old_val} =} ls_command (@var{new_val})
Query or set the shell command used by Octave's @code{ls} command.
@xseealso{@ref{XREFls,,ls}}
@end deftypefn


@c dir scripts/miscellaneous/dir.m
@anchor{XREFdir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} dir
@deftypefnx {} {} dir @var{directory}
@deftypefnx {} {[@var{list}] =} dir (@var{directory})
Display file listing for directory @var{directory}.

If @var{directory} is not specified then list the present working directory.

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

@table @asis
@item name
File or directory name.

@item folder
Location of file or directory

@item date
Timestamp of file modification (string value).

@item bytes
File size in bytes.

@item isdir
True if name is a directory.

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

@item statinfo
Information structure returned from @code{stat}.
@end table

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

@var{directory} is subject to shell expansion if it contains any wildcard
characters @samp{*}, @samp{?}, @samp{[]}.  If these wildcard characters are
escaped with a backslash @samp{\} (e.g., @samp{\*}) 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 @samp{\} is treated as a file separator.  On Windows, use
@code{ls} for file or folder names that contain characters that would be
treated as wildcards by @code{dir}.

Note that for symbolic links, @code{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, @code{dir} returns information
about the link.
@xseealso{@ref{XREFls,,ls}, @ref{XREFreaddir,,readdir}, @ref{XREFglob,,glob}, @ref{XREFwhat,,what}, @ref{XREFstat,,stat}, @ref{XREFlstat,,lstat}}
@end deftypefn


@c pwd libinterp/corefcn/dirfns.cc
@anchor{XREFpwd}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{dir} =} pwd ()
Return the current working directory.
@xseealso{@ref{XREFcd,,cd}, @ref{XREFdir,,dir}, @ref{XREFls,,ls}, @ref{XREFmkdir,,mkdir}, @ref{XREFrmdir,,rmdir}}
@end deftypefn


@node Password Database Functions
@section Password Database Functions

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

@table @code
@item name
The user name.

@item passwd
The encrypted password, if available.

@item uid
The numeric user id.

@item gid
The numeric group id.

@item gecos
The GECOS field.

@item dir
The home directory.

@item shell
The initial shell.
@end table

In the descriptions of the following functions, this data structure is
referred to as a @var{pw_struct}.

@c getpwent libinterp/corefcn/getpwent.cc
@anchor{XREFgetpwent}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{pw_struct} =} getpwent ()
Return a structure containing an entry from the password database,
opening it if necessary.

Once the end of the data has been reached, @code{getpwent} returns 0.
@xseealso{@ref{XREFsetpwent,,setpwent}, @ref{XREFendpwent,,endpwent}}
@end deftypefn


@c getpwuid libinterp/corefcn/getpwent.cc
@anchor{XREFgetpwuid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{pw_struct} =} getpwuid (@var{uid}).
Return a structure containing the first entry from the password database
with the user ID @var{uid}.

If the user ID does not exist in the database, @code{getpwuid} returns 0.
@xseealso{@ref{XREFgetpwnam,,getpwnam}}
@end deftypefn


@c getpwnam libinterp/corefcn/getpwent.cc
@anchor{XREFgetpwnam}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{pw_struct} =} getpwnam (@var{name})
Return a structure containing the first entry from the password database
with the user name @var{name}.

If the user name does not exist in the database, @code{getpwname} returns 0.
@xseealso{@ref{XREFgetpwuid,,getpwuid}}
@end deftypefn


@c setpwent libinterp/corefcn/getpwent.cc
@anchor{XREFsetpwent}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{status}, @var{msg}] =} setpwent ()
Return the internal pointer to the beginning of the password database.
@xseealso{@ref{XREFgetpwent,,getpwent}, @ref{XREFendpwent,,endpwent}}
@end deftypefn


@c endpwent libinterp/corefcn/getpwent.cc
@anchor{XREFendpwent}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{status}, @var{msg}] =} endpwent ()
Close the password database.
@xseealso{@ref{XREFgetpwent,,getpwent}, @ref{XREFsetpwent,,setpwent}}
@end deftypefn


@node Group Database Functions
@section Group Database Functions

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

@table @code
@item name
The user name.

@item passwd
The encrypted password, if available.

@item gid
The numeric group id.

@item mem
The members of the group.
@end table

In the descriptions of the following functions, this data structure is
referred to as a @var{grp_struct}.

@c getgrent libinterp/corefcn/getgrent.cc
@anchor{XREFgetgrent}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{grp_struct} =} getgrent ()
Return an entry from the group database, opening it if necessary.

Once the end of data has been reached, @code{getgrent} returns 0.
@xseealso{@ref{XREFsetgrent,,setgrent}, @ref{XREFendgrent,,endgrent}}
@end deftypefn


@c getgrgid libinterp/corefcn/getgrent.cc
@anchor{XREFgetgrgid}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{grp_struct} =} getgrgid (@var{gid}).
Return the first entry from the group database with the group ID
@var{gid}.

If the group ID does not exist in the database, @code{getgrgid} returns 0.
@xseealso{@ref{XREFgetgrnam,,getgrnam}}
@end deftypefn


@c getgrnam libinterp/corefcn/getgrent.cc
@anchor{XREFgetgrnam}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{grp_struct} =} getgrnam (@var{name})
Return the first entry from the group database with the group name
@var{name}.

If the group name does not exist in the database, @code{getgrnam} returns 0.
@xseealso{@ref{XREFgetgrgid,,getgrgid}}
@end deftypefn


@c setgrent libinterp/corefcn/getgrent.cc
@anchor{XREFsetgrent}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{status}, @var{msg}] =} setgrent ()
Return the internal pointer to the beginning of the group database.
@xseealso{@ref{XREFgetgrent,,getgrent}, @ref{XREFendgrent,,endgrent}}
@end deftypefn


@c endgrent libinterp/corefcn/getgrent.cc
@anchor{XREFendgrent}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{status}, @var{msg}] =} endgrent ()
Close the group database.
@xseealso{@ref{XREFgetgrent,,getgrent}, @ref{XREFsetgrent,,setgrent}}
@end deftypefn


@node System Information
@section System Information

@c computer scripts/miscellaneous/computer.m
@anchor{XREFcomputer}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} computer ()
@deftypefnx {} {@var{comp} =} computer ()
@deftypefnx {} {[@var{comp}, @var{maxsize}] =} computer ()
@deftypefnx {} {[@var{comp}, @var{maxsize}, @var{endian}] =} computer ()
@deftypefnx {} {@var{arch} =} computer ("arch")
Print or return a string of the form @var{cpu}-@var{vendor}-@var{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:

@example
@group
computer ()
   @print{} x86_64-pc-linux-gnu

mycomp = computer ()
   @result{} mycomp = x86_64-pc-linux-gnu
@end group
@end example

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 (@qcode{"B"} for big-endian or @qcode{"L"}
for little-endian).

If the argument @qcode{"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.
@xseealso{@ref{XREFisunix,,isunix}, @ref{XREFismac,,ismac}, @ref{XREFispc,,ispc}}
@end deftypefn


@c uname libinterp/corefcn/syscalls.cc
@anchor{XREFuname}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {[@var{uts}, @var{err}, @var{msg}] =} uname ()
Return system information in the structure.

For example:

@example
@group
uname ()
   @result{} @{
         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
      @}
@end group
@end example

If successful, @var{err} is 0 and @var{msg} is an empty string.
Otherwise, @var{err} is nonzero and @var{msg} contains a
system-dependent error message.
@end deftypefn


@c nproc libinterp/corefcn/nproc.cc
@anchor{XREFnproc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{n} =} nproc ()
@deftypefnx {} {@var{n} =} nproc (@var{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 @var{query}, modify how processors
are counted as follows:

@table @code
@item all
total number of processors.

@item current
processors available to the current process.

@item overridable
same as @code{current}, but overridable through the
@w{@env{OMP_NUM_THREADS}}@ environment variable.
@end table
@end deftypefn


@c ispc scripts/miscellaneous/ispc.m
@anchor{XREFispc}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} ispc ()
Return true if Octave is running on a Windows system and false otherwise.
@xseealso{@ref{XREFisunix,,isunix}, @ref{XREFismac,,ismac}}
@end deftypefn


@c isunix scripts/miscellaneous/isunix.m
@anchor{XREFisunix}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isunix ()
Return true if Octave is running on a Unix-like system and false otherwise.
@xseealso{@ref{XREFismac,,ismac}, @ref{XREFispc,,ispc}}
@end deftypefn


@c ismac scripts/miscellaneous/ismac.m
@anchor{XREFismac}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} ismac ()
Return true if Octave is running on a Mac OS X system and false otherwise.
@xseealso{@ref{XREFisunix,,isunix}, @ref{XREFispc,,ispc}}
@end deftypefn


@c isieee libinterp/corefcn/sysdep.cc
@anchor{XREFisieee}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isieee ()
Return true if your computer @emph{claims} to conform to the IEEE@tie{}754
standard for floating point calculations.

No actual tests are performed.
@end deftypefn


@c isdeployed scripts/miscellaneous/isdeployed.m
@anchor{XREFisdeployed}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{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.
@end deftypefn


@c isstudent libinterp/corefcn/utils.cc
@anchor{XREFisstudent}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} isstudent ()
Return true if running in the student edition of @sc{matlab}.

@code{isstudent} always returns false in Octave.
@xseealso{@ref{XREFfalse,,false}}
@end deftypefn


@c OCTAVE_HOME libinterp/corefcn/defaults.cc
@anchor{XREFOCTAVE_HOME}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{dir} =} OCTAVE_HOME ()
Return the name of the top-level Octave installation directory.

OCTAVE_HOME corresponds to the configuration variable @var{prefix}.
@xseealso{@ref{XREFEXEC_PATH,,EXEC_PATH}, @ref{XREFIMAGE_PATH,,IMAGE_PATH}, @ref{XREFOCTAVE_EXEC_HOME,,OCTAVE_EXEC_HOME}}
@end deftypefn


@c OCTAVE_EXEC_HOME libinterp/corefcn/defaults.cc
@anchor{XREFOCTAVE_EXEC_HOME}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{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 @var{exec_prefix}.
@xseealso{@ref{XREFEXEC_PATH,,EXEC_PATH}, @ref{XREFIMAGE_PATH,,IMAGE_PATH}, @ref{XREFOCTAVE_HOME,,OCTAVE_HOME}}
@end deftypefn


@c matlabroot scripts/path/matlabroot.m
@anchor{XREFmatlabroot}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{dir} =} matlabroot ()
Return the name of the top-level Octave installation directory.

This is an alias for the function @w{@code{OCTAVE_HOME}}@ provided for
compatibility.
@xseealso{@ref{XREFOCTAVE_HOME,,OCTAVE_HOME}}
@end deftypefn


@c user_config_dir libinterp/corefcn/defaults.cc
@anchor{XREFuser_config_dir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {cfg_dir =} user_config_dir ()
Return the (platform-specific) directory for user configuration.
@xseealso{@ref{XREFuser_data_dir,,user_data_dir}}
@end deftypefn


@c user_data_dir libinterp/corefcn/defaults.cc
@anchor{XREFuser_data_dir}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {data_dir =} user_data_dir ()
Return the (platform-specific) directory for user data.
@xseealso{@ref{XREFuser_config_dir,,user_config_dir}}
@end deftypefn


@c OCTAVE_VERSION libinterp/corefcn/defaults.cc
@anchor{XREFOCTAVE_VERSION}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{verstr} =} OCTAVE_VERSION ()
Return the version number of Octave as a string.
@xseealso{@ref{XREFver,,ver}, @ref{XREFversion,,version}}
@end deftypefn


@c version scripts/miscellaneous/version.m
@anchor{XREFversion}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{v} =} version ()
@deftypefnx {} {[@var{v}, @var{d}] =} version ()
@deftypefnx {} {@var{v} =} version (@var{feature})
Get version information for Octave.

If called without input argument, the first return value @var{v} gives the
version number of Octave as a string.  The second return value @var{d} holds
the release date as a string.

The following options can be passed for @var{feature}:

@table @asis
@item @qcode{"-date"}
for the release date of the running build,

@item @qcode{"-description"}
for a description of the release (always an empty string),

@item @qcode{"-release"}
for the name of the running build (always an empty string),

@item @qcode{"-java"}
for version information of the Java @nospell{VM},

@item @qcode{"-fftw"}
for version information for the linked @sc{fftw},

@item @qcode{"-blas"}
for version information for the linked @sc{blas},

@item @qcode{"-lapack"}
for version information for the linked @sc{lapack}.

@item @qcode{"-hgid"}
the mercurial ID of the sources used to build Octave.
@end table

The information returned for the @qcode{"-blas"} and @qcode{"-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
@w{@env{OCTAVE_VERSION}}@ provided for compatibility.
@xseealso{@ref{XREFOCTAVE_VERSION,,OCTAVE_VERSION}, @ref{XREFver,,ver}}
@end deftypefn


@c ver scripts/miscellaneous/ver.m
@anchor{XREFver}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} ver
@deftypefnx {} {} ver Octave
@deftypefnx {} {} ver @var{package}
@deftypefnx {} {v =} ver (@dots{})

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 @var{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.

@table @code
@item Name
Package name.

@item Version
Version of the package.

@item Release
Release of the package (currently unused, defaults to @code{[]}).

@item Date
Date that the version was released.
@end table

@xseealso{@ref{XREFversion,,version}, @ref{XREFusejava,,usejava}, @ref{XREFpkg,,pkg}}
@end deftypefn


@c compare_versions scripts/miscellaneous/compare_versions.m
@anchor{XREFcompare_versions}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} compare_versions (@var{v1}, @var{v2}, @var{operator})
Compare two version strings using the given @var{operator}.

This function assumes that versions @var{v1} and @var{v2} are arbitrarily
long strings made of numeric and period characters possibly followed by an
arbitrary string (e.g., @qcode{"1.2.3"}, @qcode{"0.3"}, @qcode{"0.1.2+"},
or @qcode{"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., @qcode{"1.1"} would be
padded to be @qcode{"1.1.0"} when being compared with @qcode{"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

@itemize @bullet
@item
@qcode{"=="}
equal

@item
@qcode{"<"}
less than

@item
@qcode{"<="}
less than or equal to

@item
@qcode{">"}
greater than

@item
@qcode{">="}
greater than or equal to

@item @qcode{"!="}, @qcode{"~="}
not equal

@end itemize

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


@c verLessThan scripts/miscellaneous/verLessThan.m
@anchor{XREFverLessThan}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{tf} =} verLessThan (@var{package}, @var{version})
Return true if the installed version of the package is less than
@var{version}.

@var{package} is the name of the package to check.  Use @qcode{"Octave"} as
the @var{package} to check the version of Octave itself.

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

Examples:

@example
@group
tf = verLessThan ("Octave", "5")
@result{} tf = 0

tf = verLessThan ("io", "2.4.12")
@result{} ...

if (! verLessThan ("Octave", "5"))
  ## ... use new Octave 5 features ...
endif
@end group
@end example

@xseealso{@ref{XREFcompare_versions,,compare_versions}, @ref{XREFversion,,version}, @ref{XREFver,,ver}, @ref{XREFpkg,,pkg}}
@end deftypefn


@c license scripts/miscellaneous/license.m
@anchor{XREFlicense}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} license
@deftypefnx {} {} license inuse
@deftypefnx {} {} license inuse @var{feature}
@deftypefnx {} {} license ("inuse")
@deftypefnx {} {@var{license_struct} =} license ("inuse")
@deftypefnx {} {@var{license_struct} =} license ("inuse", @var{feature})
@deftypefnx {} {@var{status} =} license ("test", @var{feature})
@deftypefnx {} {@var{status} =} license ("checkout", @var{feature})
@deftypefnx {} {[@var{status}, @var{errmsg}] =} license ("checkout", @var{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 @sc{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: @code{inuse}, @code{test}, and @code{checkout}.
The optional @var{feature} argument can either be @qcode{"octave"} (core)
or the name of an Octave package.

@table @asis
@item @qcode{"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 @qcode{"feature"}, and @qcode{"user"}.

@item @qcode{"test"}
Return true if the specified @var{feature} is installed, false otherwise.

An optional third argument @qcode{"enable"} or @qcode{"disable"} is
accepted but ignored.

@item @qcode{"checkout"}
Return true if the specified @var{feature} is installed, false otherwise.
An optional second output will have an error message if a package is not
installed.

@end table

@xseealso{@ref{XREFpkg,,pkg}, @ref{XREFver,,ver}, @ref{XREFversion,,version}}
@end deftypefn


@c memory scripts/miscellaneous/memory.m
@anchor{XREFmemory}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} memory ()
@deftypefnx {} {[@var{userdata}, @var{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 @var{userdata} is a structure with the following fields
containing data for the Octave process:

@table @code
@item MaxPossibleArrayBytes
Maximum size for an array to be allocated.  Be aware that this includes
@emph{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.

@item MemAvailableAllArrays
The total size of available memory in bytes.

@item 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.

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

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

@end table

The output argument @var{systemdata} is a nested structure with the
following fields containing information about the system's memory:

@table @code
@item PhysicalMemory.Available
The currently available physical memory in bytes.

@item PhysicalMemory.Total
The total physical memory in bytes.

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

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

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

@item VirtualAddressSpace.Total
The total virtual address space in bytes.

@end table

Example #1 : print formatted table of memory usage

@example
@group
memory ()
@result{}
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
@end group
@end example

Example #2 : return structs with memory usage information

@example
[userdata, systemdata] = memory ()
@result{}
 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
@end example

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

@xseealso{@ref{XREFcomputer,,computer}, @ref{XREFgetpid,,getpid}, @ref{XREFgetrusage,,getrusage}, @ref{XREFnproc,,nproc}, @ref{XREFuname,,uname}}
@end deftypefn


@c getrusage libinterp/corefcn/getrusage.cc
@anchor{XREFgetrusage}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{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:

@table @code
@item idrss
Unshared data size.

@item inblock
Number of block input operations.

@item isrss
Unshared stack size.

@item ixrss
Shared memory size.

@item majflt
Number of major page faults.

@item maxrss
Maximum data size.

@item minflt
Number of minor page faults.

@item msgrcv
Number of messages received.

@item msgsnd
Number of messages sent.

@item nivcsw
Number of involuntary context switches.

@item nsignals
Number of signals received.

@item nswap
Number of swaps.

@item nvcsw
Number of voluntary context switches.

@item oublock
Number of block output operations.

@item stime
A structure containing the system CPU time used.  The structure has the
elements @code{sec} (seconds) @code{usec} (microseconds).

@item utime
A structure containing the user CPU time used.  The structure has the
elements @code{sec} (seconds) @code{usec} (microseconds).
@end table
@end deftypefn


@c winqueryreg libinterp/corefcn/sysdep.cc
@anchor{XREFwinqueryreg}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{value} =} winqueryreg (@var{rootkey}, @var{subkey}, @var{valuename})
@deftypefnx {} {@var{value} =} winqueryreg (@var{rootkey}, @var{subkey})
@deftypefnx {} {@var{names} =} winqueryreg (@code{"name"}, @var{rootkey}, @var{subkey})

Query names or value from the Windows registry.

On Windows, return the value of the registry key @var{subkey} from the root key
@var{rootkey}.  You can specify the name of the queried registry value with the
optional argument @var{valuename}.  Otherwise, if called with only two
arguments or @var{valuename} is empty, then the default value of @var{subkey}
is returned.  If the registry value is of type @nospell{@qcode{"REG_DWORD"}}
then @var{value} is of class int32.  If the value is of the type
@nospell{@qcode{"REG_SZ"}} or @nospell{@qcode{"REG_EXPAND_SZ"}} a string is
returned.

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

The variable @var{rootkey} must be a string with a valid root key identifier:

@table @asis
@item  @nospell{HKCR}
@itemx @nospell{HKEY_CLASSES_ROOT}

@item @nospell{HKEY_CURRENT_CONFIG}

@item  @nospell{HKCU}
@itemx @nospell{HKEY_CURRENT_USER}

@item  @nospell{HKLM}
@itemx @nospell{HKEY_LOCAL_MACHINE}


@item  @nospell{HKU}
@itemx @nospell{HKEY_USERS}


@item @nospell{HKEY_PERFORMANCE_DATA}

@end table

Examples:

Get a list of value names at the key
@nospell{@qcode{'HKCU@backslashchar{}Environment'}}:

@example
@group
@var{valuenames} = winqueryreg ("name", "HKEY_CURRENT_USER", ...
                          "Environment");
@end group
@end example

For each @var{valuenames}, display the value:

@example
@group
for @var{k} = 1:numel (@var{valuenames})
  @var{val} = winqueryreg ("HKEY_CURRENT_USER", "Environment", ...
                     @var{valuenames}@{@var{k}@});
  @var{str} = sprintf ("%s = %s", @var{valuenames}@{@var{k}@}, num2str (@var{val}));
  disp (@var{str});
endfor
@end group
@end example

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


@node Hashing Functions
@section 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 @code{hash} function to calculate hash values of
strings and files, the latter in combination with the @code{fileread}
function.  The @code{hash} function supports many commonly used hash
methods.

@c hash libinterp/corefcn/hash.cc
@anchor{XREFhash}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn {} {@var{hashval} =} hash ("@var{hashfcn}", @var{str})
Calculate the hash value of the string @var{str} using the hash function
@var{hashfcn}.

The available hash functions are given in the table below.

@table @samp
@item MD2
Message-Digest Algorithm 2 (RFC 1319).

@item MD4
Message-Digest Algorithm 4 (RFC 1320).

@item MD5
Message-Digest Algorithm 5 (RFC 1321).

@item SHA1
Secure Hash Algorithm 1 (RFC 3174)

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

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

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

@item SHA512
Secure Hash Algorithm 2 (512 Bits, RFC 6234)
@end table

To calculate for example the MD5 hash value of the string
@nospell{@qcode{"abc"}} the @code{hash} function is called as follows:

@example
@group
hash ("md5", "abc")
     @print{} ans = 900150983cd24fb0d6963f7d28e17f72
@end group
@end example

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

@example
@group
hash ("sha1", "abc")
     @print{} ans = a9993e364706816aba3e25717850c26c9cd0d89d
@end group
@end example

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

@example
@group
hash ("md5", fileread (file));
@end group
@end example

@end deftypefn