|
2670
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
2333
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
2670
|
5 @node System Utilities, Tips, Audio Processing, Top |
|
2333
|
6 @chapter System Utilities |
|
|
7 |
|
|
8 This chapter describes the functions that are available to allow you to |
|
|
9 get information about what is happening outside of Octave, while it is |
|
|
10 still running, and use this information in your program. For example, |
|
|
11 you can get information about environment variables, the current time, |
|
|
12 and even start other programs from the Octave prompt. |
|
|
13 |
|
|
14 @menu |
|
|
15 * Timing Utilities:: |
|
|
16 * Filesystem Utilities:: |
|
2670
|
17 * Controlling Subprocesses:: |
|
|
18 * Process ID Information:: |
|
|
19 * Environment Variables:: |
|
|
20 * Current Working Directory:: |
|
2460
|
21 * Password Database Functions:: |
|
2475
|
22 * Group Database Functions:: |
|
2333
|
23 * System Information:: |
|
|
24 @end menu |
|
|
25 |
|
|
26 @node Timing Utilities, Filesystem Utilities, System Utilities, System Utilities |
|
|
27 @section Timing Utilities |
|
|
28 |
|
2670
|
29 Octave's core set of functions for manipulating time values are |
|
|
30 patterned after the corresponding functions from the standard C library. |
|
|
31 Several of these functions use a data structure for time that includes |
|
|
32 the following elements: |
|
2333
|
33 |
|
|
34 @table @code |
|
|
35 @item usec |
|
|
36 Microseconds after the second (0-999999). |
|
|
37 |
|
|
38 @item sec |
|
|
39 Seconds after the minute (0-61). This number can be 61 to account |
|
|
40 for leap seconds. |
|
|
41 |
|
|
42 @item min |
|
|
43 Minutes after the hour (0-59). |
|
|
44 |
|
|
45 @item hour |
|
|
46 Hours since midnight (0-23). |
|
|
47 |
|
|
48 @item mday |
|
|
49 Day of the month (1-31). |
|
|
50 |
|
|
51 @item mon |
|
|
52 Months since January (0-11). |
|
|
53 |
|
|
54 @item year |
|
|
55 Years since 1900. |
|
|
56 |
|
|
57 @item wday |
|
|
58 Days since Sunday (0-6). |
|
|
59 |
|
|
60 @item yday |
|
|
61 Days since January 1 (0-365). |
|
|
62 |
|
|
63 @item isdst |
|
|
64 Daylight Savings Time flag. |
|
|
65 |
|
|
66 @item zone |
|
|
67 Time zone. |
|
|
68 @end table |
|
|
69 |
|
2670
|
70 @noindent |
|
|
71 In the descriptions of the following functions, this structure is |
|
|
72 referred to as a @var{tm_struct}. |
|
|
73 |
|
|
74 @deftypefn {Loadable Function} {} time () |
|
|
75 Return the current time as the number of seconds since the epoch. The |
|
|
76 epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan |
|
|
77 1970. |
|
|
78 @end deftypefn |
|
|
79 |
|
|
80 @deftypefn {Function File} {} ctime (@var{t}) |
|
|
81 Convert a value returned from @code{time} (or any other nonnegative |
|
|
82 integer), to the local time and return a string of the same form as |
|
|
83 @code{asctime}. The function @code{ctime (time)} is equivalent to |
|
|
84 @code{asctime (localtime (time))}. |
|
|
85 @end deftypefn |
|
|
86 |
|
|
87 @deftypefn {Loadable Function} {} gmtime (@var{t}) |
|
|
88 Given a value returned from time (or any nonnegative integer), |
|
|
89 return a time structure corresponding to CUT. |
|
2449
|
90 @end deftypefn |
|
2333
|
91 |
|
2465
|
92 @deftypefn {Loadable Function} {} localtime (@var{t}) |
|
2449
|
93 Given a value returned from time (or any nonnegative integer), |
|
|
94 return a time structure corresponding to the local time zone. |
|
|
95 @end deftypefn |
|
2333
|
96 |
|
2670
|
97 @deftypefn {Loadable Function} {} mktime (@var{tm_struct}) |
|
|
98 Convert a time structure to the number of seconds since the epoch. |
|
2449
|
99 @end deftypefn |
|
2333
|
100 |
|
2670
|
101 @deftypefn {Function File} {} asctime (@var{tm_struct}) |
|
2449
|
102 Convert a time structure to a string using the following five-field |
|
|
103 format: Thu Mar 28 08:40:14 1996. The function @code{ctime (time)} is |
|
|
104 equivalent to @code{asctime (localtime (time))}. |
|
|
105 @end deftypefn |
|
2333
|
106 |
|
2670
|
107 @deftypefn {Loadable Function} {} strftime (@var{tm_struct}) |
|
2449
|
108 Format a time structure in a flexible way using @samp{%} substitutions |
|
|
109 similar to those in @code{printf}. Except where noted, substituted |
|
|
110 fields have a fixed size; numeric fields are padded if necessary. |
|
|
111 Padding is with zeros by default; for fields that display a single |
|
|
112 number, padding can be changed or inhibited by following the @samp{%} |
|
|
113 with one of the modifiers described below. Unknown field specifiers are |
|
|
114 copied as normal characters. All other characters are copied to the |
|
|
115 output without change. |
|
2333
|
116 |
|
|
117 Octave's @code{strftime} function supports a superset of the ANSI C |
|
|
118 field specifiers. |
|
|
119 |
|
|
120 @noindent |
|
|
121 Literal character fields: |
|
|
122 |
|
|
123 @table @code |
|
|
124 @item % |
|
|
125 % character. |
|
|
126 |
|
|
127 @item n |
|
|
128 Newline character. |
|
|
129 |
|
|
130 @item t |
|
|
131 Tab character. |
|
|
132 @end table |
|
|
133 |
|
|
134 @noindent |
|
|
135 Numeric modifiers (a nonstandard extension): |
|
|
136 |
|
|
137 @table @code |
|
2653
|
138 @item - (dash) |
|
2333
|
139 Do not pad the field. |
|
|
140 |
|
2653
|
141 @item _ (underscore) |
|
2333
|
142 Pad the field with spaces. |
|
|
143 @end table |
|
|
144 |
|
|
145 @noindent |
|
|
146 Time fields: |
|
|
147 |
|
|
148 @table @code |
|
|
149 @item %H |
|
|
150 Hour (00-23). |
|
|
151 |
|
|
152 @item %I |
|
|
153 Hour (01-12). |
|
|
154 |
|
|
155 @item %k |
|
|
156 Hour (0-23). |
|
|
157 |
|
|
158 @item %l |
|
|
159 Hour (1-12). |
|
|
160 |
|
|
161 @item %M |
|
|
162 Minute (00-59). |
|
|
163 |
|
|
164 @item %p |
|
|
165 Locale's AM or PM. |
|
|
166 |
|
|
167 @item %r |
|
|
168 Time, 12-hour (hh:mm:ss [AP]M). |
|
|
169 |
|
|
170 @item %R |
|
|
171 Time, 24-hour (hh:mm). |
|
|
172 |
|
|
173 @item %s |
|
|
174 Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension). |
|
|
175 |
|
|
176 @item %S |
|
|
177 Second (00-61). |
|
|
178 |
|
|
179 @item %T |
|
|
180 Time, 24-hour (hh:mm:ss). |
|
|
181 |
|
|
182 @item %X |
|
|
183 Locale's time representation (%H:%M:%S). |
|
|
184 |
|
|
185 @item %Z |
|
|
186 Time zone (EDT), or nothing if no time zone is determinable. |
|
|
187 @end table |
|
|
188 |
|
|
189 @noindent |
|
|
190 Date fields: |
|
|
191 |
|
|
192 @table @code |
|
|
193 @item %a |
|
|
194 Locale's abbreviated weekday name (Sun-Sat). |
|
|
195 |
|
|
196 @item %A |
|
|
197 Locale's full weekday name, variable length (Sunday-Saturday). |
|
|
198 |
|
|
199 @item %b |
|
|
200 Locale's abbreviated month name (Jan-Dec). |
|
|
201 |
|
|
202 @item %B |
|
|
203 Locale's full month name, variable length (January-December). |
|
|
204 |
|
|
205 @item %c |
|
|
206 Locale's date and time (Sat Nov 04 12:02:33 EST 1989). |
|
|
207 |
|
|
208 @item %C |
|
|
209 Century (00-99). |
|
|
210 |
|
|
211 @item %d |
|
|
212 Day of month (01-31). |
|
|
213 |
|
|
214 @item %e |
|
|
215 Day of month ( 1-31). |
|
|
216 |
|
|
217 @item %D |
|
|
218 Date (mm/dd/yy). |
|
|
219 |
|
|
220 @item %h |
|
|
221 Same as %b. |
|
|
222 |
|
|
223 @item %j |
|
|
224 Day of year (001-366). |
|
|
225 |
|
|
226 @item %m |
|
|
227 Month (01-12). |
|
|
228 |
|
|
229 @item %U |
|
|
230 Week number of year with Sunday as first day of week (00-53). |
|
|
231 |
|
|
232 @item %w |
|
|
233 Day of week (0-6). |
|
|
234 |
|
|
235 @item %W |
|
|
236 Week number of year with Monday as first day of week (00-53). |
|
|
237 |
|
|
238 @item %x |
|
|
239 Locale's date representation (mm/dd/yy). |
|
|
240 |
|
|
241 @item %y |
|
|
242 Last two digits of year (00-99). |
|
|
243 |
|
|
244 @item %Y |
|
|
245 Year (1970-). |
|
|
246 @end table |
|
2449
|
247 @end deftypefn |
|
2333
|
248 |
|
2670
|
249 Most of the remaining functions described in this section are not |
|
|
250 patterned after the standard C library. Some are available for |
|
|
251 compatiblity with @sc{Matlab} and others are provided because they are |
|
|
252 useful. |
|
|
253 |
|
2449
|
254 @deftypefn {Function File} {} clock () |
|
|
255 Return a vector containing the current year, month (1-12), day (1-31), |
|
|
256 hour (0-23), minute (0-59) and second (0-61). For example, |
|
2333
|
257 |
|
|
258 @example |
|
|
259 octave:13> clock |
|
|
260 ans = |
|
|
261 |
|
|
262 1993 8 20 4 56 1 |
|
|
263 @end example |
|
|
264 |
|
|
265 The function clock is more accurate on systems that have the |
|
|
266 @code{gettimeofday} function. |
|
2449
|
267 @end deftypefn |
|
2333
|
268 |
|
2449
|
269 @deftypefn {Function File} {} date () |
|
|
270 Returns the date as a character string in the form DD-MMM-YY. For |
|
|
271 example, |
|
2333
|
272 |
|
|
273 @example |
|
|
274 octave:13> date |
|
|
275 ans = 20-Aug-93 |
|
|
276 @end example |
|
2449
|
277 @end deftypefn |
|
2333
|
278 |
|
2449
|
279 @deftypefn {Function File} {} etime (@var{t1}, @var{t2}) |
|
|
280 Return the difference (in seconds) between two time values returned from |
|
|
281 @code{clock}. For example: |
|
2333
|
282 |
|
|
283 @example |
|
|
284 t0 = clock (); |
|
|
285 # many computations later... |
|
|
286 elapsed_time = etime (clock (), t0); |
|
|
287 @end example |
|
|
288 |
|
|
289 @noindent |
|
|
290 will set the variable @code{elapsed_time} to the number of seconds since |
|
|
291 the variable @code{t0} was set. |
|
2449
|
292 @end deftypefn |
|
2333
|
293 |
|
2449
|
294 @deftypefn {Built-in Function} {[@var{total}, @var{user}, @var{system}] =} cputime (); |
|
|
295 Return the CPU time used by your Octave session. The first output is |
|
2333
|
296 the total time spent executing your process and is equal to the sum of |
|
|
297 second and third outputs, which are the number of CPU seconds spent |
|
|
298 executing in user mode and the number of CPU seconds spent executing in |
|
|
299 system mode, respectively. If your system does not have a way to report |
|
|
300 CPU time usage, @code{cputime} returns 0 for each of its output values. |
|
2653
|
301 Note that because Octave used some CPU time to start, it is reasonable |
|
|
302 to check to see if @code{cputime} works by checking to see if the total |
|
|
303 CPU time used is nonzero. |
|
2449
|
304 @end deftypefn |
|
2333
|
305 |
|
2449
|
306 @deftypefn {Function File} {} is_leap_year (@var{year}) |
|
|
307 Return 1 if the given year is a leap year and 0 otherwise. If no |
|
|
308 arguments are provided, @code{is_leap_year} will use the current year. |
|
|
309 For example, |
|
2333
|
310 |
|
|
311 @example |
|
|
312 octave:13> is_leap_year (2000) |
|
|
313 ans = 1 |
|
|
314 @end example |
|
2449
|
315 @end deftypefn |
|
2333
|
316 |
|
2653
|
317 @deftypefn {Function File} {} tic () |
|
|
318 @deftypefnx {Function File} {} toc () |
|
|
319 These functions set and check a wall-clock timer. For example, |
|
|
320 |
|
|
321 @example |
|
|
322 tic (); |
|
|
323 # many computations later... |
|
|
324 elapsed_time = toc (); |
|
|
325 @end example |
|
|
326 |
|
|
327 @noindent |
|
|
328 will set the variable @code{elapsed_time} to the number of seconds since |
|
|
329 the most recent call to the function @code{tic}. |
|
|
330 |
|
|
331 If you are more interested in the CPU time that your process used, you |
|
|
332 should use the @code{cputime} function instead. The @code{tic} and |
|
|
333 @code{toc} functions report the actual wall clock time that elapsed |
|
|
334 between the calls. This may include time spent processing other jobs or |
|
|
335 doing nothing at all. For example, |
|
|
336 |
|
|
337 @example |
|
|
338 @group |
|
|
339 tic (); sleep (5); toc () |
|
|
340 @result{} 5 |
|
|
341 t = cputime (); sleep (5); cputime () - t |
|
|
342 @result{} 0 |
|
|
343 @end group |
|
|
344 @end example |
|
|
345 |
|
|
346 @noindent |
|
|
347 (This example also illustrates that the CPU timer may have a fairly |
|
|
348 coarse resolution.) |
|
|
349 @end deftypefn |
|
|
350 |
|
2670
|
351 @deftypefn {Built-in Function} {} pause (@var{seconds}) |
|
|
352 Suspend the execution of the program. If invoked without any arguments, |
|
|
353 Octave waits until you type a character. With a numeric argument, it |
|
|
354 pauses for the given number of seconds. For example, the following |
|
|
355 statement prints a message and then waits 5 seconds before clearing the |
|
|
356 screen. |
|
|
357 |
|
|
358 @example |
|
|
359 @group |
|
|
360 fprintf (stderr, "wait please...\n"); |
|
|
361 pause (5); |
|
|
362 clc; |
|
|
363 @end group |
|
|
364 @end example |
|
|
365 @end deftypefn |
|
|
366 |
|
|
367 @deftypefn {Built-in Function} {} sleep (@var{seconds}) |
|
|
368 Suspend the execution of the program. |
|
|
369 @end deftypefn |
|
|
370 |
|
|
371 @deftypefn {Built-in Function} {} usleep (@var{microseconds}) |
|
|
372 Suspend the execution of the program. |
|
|
373 @end deftypefn |
|
|
374 |
|
|
375 @node Filesystem Utilities, Controlling Subprocesses, Timing Utilities, System Utilities |
|
2333
|
376 @section Filesystem Utilities |
|
|
377 |
|
|
378 Octave includes the following functions for renaming and deleting files, |
|
|
379 creating, deleting, and reading directories, and for getting information |
|
|
380 about the status of files. |
|
|
381 |
|
2670
|
382 @deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rename (@var{old}, @var{new}) |
|
|
383 Change the name of file @var{old} to @var{new}. |
|
|
384 |
|
|
385 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
386 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
387 system-dependent error message. |
|
2449
|
388 @end deftypefn |
|
2333
|
389 |
|
2670
|
390 @deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} unlink (@var{file}) |
|
|
391 Delete @var{file}. |
|
|
392 |
|
|
393 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
394 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
395 system-dependent error message. |
|
2449
|
396 @end deftypefn |
|
2333
|
397 |
|
2670
|
398 @deftypefn {Built-in Function} {[@var{files}, @var{err}, @var{msg}] =} readdir (@var{dir}) |
|
|
399 Return names of the files in the directory @var{dir} as an array of |
|
|
400 strings. If an error occurs, return an empty matrix in @var{files}. |
|
|
401 |
|
|
402 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
403 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
404 system-dependent error message. |
|
2449
|
405 @end deftypefn |
|
2333
|
406 |
|
2670
|
407 @deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkdir (@var{dir}) |
|
|
408 Create a directory named @var{dir}. |
|
|
409 |
|
|
410 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
411 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
412 system-dependent error message. |
|
2449
|
413 @end deftypefn |
|
2333
|
414 |
|
2670
|
415 @deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} rmdir (@var{dir}) |
|
|
416 Remove the directory named @var{dir}. |
|
|
417 |
|
|
418 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
419 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
420 system-dependent error message. |
|
|
421 @end deftypefn |
|
|
422 |
|
|
423 @deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} mkfifo (@var{name}) |
|
|
424 Create a FIFO special file. |
|
|
425 |
|
|
426 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
427 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
428 system-dependent error message. |
|
2449
|
429 @end deftypefn |
|
|
430 |
|
2333
|
431 @c XXX FIXME XXX -- this needs to be explained, but I don't feel up to |
|
|
432 @c it just now... |
|
|
433 |
|
2449
|
434 @deftypefn {Built-in Function} {} umask (@var{mask}) |
|
2670
|
435 Set the permission mask for file creation. The parameter @var{mask} is |
|
|
436 interpreted as an octal number. |
|
2449
|
437 @end deftypefn |
|
|
438 |
|
2670
|
439 @deftypefn {Built-in Function} {[info, err, msg] =} stat (@var{file}) |
|
|
440 @deftypefnx {Built-in Function} {[info, err, msg] =} lstat (@var{file}) |
|
|
441 Return a structure @var{s} containing the following information about |
|
|
442 @var{file}. |
|
|
443 |
|
|
444 @table @code |
|
|
445 @item dev |
|
|
446 ID of device containing a directory entry for this file. |
|
|
447 |
|
|
448 @item ino |
|
|
449 File number of the file. |
|
|
450 |
|
|
451 @item modestr |
|
|
452 File mode, as a string of ten letters or dashes as would be returned by |
|
|
453 @kbd{ls -l}. |
|
|
454 |
|
|
455 @item nlink |
|
|
456 Number of links. |
|
|
457 |
|
|
458 @item uid |
|
|
459 User ID of file's owner. |
|
|
460 |
|
|
461 @item gid |
|
|
462 Group ID of file's group. |
|
|
463 |
|
|
464 @item rdev |
|
|
465 ID of device for block or character special files. |
|
|
466 |
|
|
467 @item size |
|
|
468 Size in bytes. |
|
|
469 |
|
|
470 @item atime |
|
|
471 Time of last access in the same form as time values returned from |
|
|
472 @code{time}. @xref{Timing Utilities}. |
|
|
473 |
|
|
474 @item mtime |
|
|
475 Time of last modification in the same form as time values returned from |
|
|
476 @code{time}. @xref{Timing Utilities}. |
|
|
477 |
|
|
478 @item ctime |
|
|
479 Time of last file status change in the same form as time values returned from |
|
|
480 @code{time}. @xref{Timing Utilities}. |
|
2333
|
481 |
|
2670
|
482 @item blksize |
|
|
483 Size of blocks in the file. |
|
|
484 |
|
|
485 @item blocks |
|
|
486 Number of blocks allocated for file. |
|
|
487 @end table |
|
|
488 |
|
|
489 If the call is successful @var{err} is 0 and @var{msg} is an empty |
|
|
490 string. If the file does not exist, or some other error occurs, @var{s} |
|
|
491 is an empty matrix, @var{err} is -1, and @var{msg} contains the |
|
|
492 corresponding system error message. |
|
|
493 |
|
|
494 If @var{file} is a symbolic link, @code{stat} will return information |
|
|
495 about the actual file the is referenced by the link. Use @code{lstat} |
|
|
496 if you want information about the symbolic link itself. |
|
|
497 |
|
|
498 For example, |
|
|
499 |
|
|
500 @example |
|
|
501 @group |
|
|
502 [s, err, msg] = stat ("/vmlinuz") |
|
|
503 |
|
|
504 @result{} s = |
|
|
505 @{ |
|
|
506 atime = 855399756 |
|
|
507 rdev = 0 |
|
|
508 ctime = 847219094 |
|
|
509 uid = 0 |
|
|
510 size = 389218 |
|
|
511 blksize = 4096 |
|
|
512 mtime = 847219094 |
|
|
513 gid = 6 |
|
|
514 nlink = 1 |
|
|
515 blocks = 768 |
|
|
516 modestr = -rw-r--r-- |
|
|
517 ino = 9316 |
|
|
518 dev = 2049 |
|
|
519 @} |
|
|
520 |
|
|
521 @result{} err = 0 |
|
|
522 |
|
|
523 @result{} msg = |
|
|
524 |
|
|
525 @end group |
|
|
526 @end example |
|
2449
|
527 @end deftypefn |
|
2333
|
528 |
|
2495
|
529 @deftypefn {Built-in Function} {} glob (@var{pattern}) |
|
|
530 Given an array of strings in @var{pattern}, return the list of file |
|
|
531 names that any of them, or an empty string if no patterns match. Tilde |
|
|
532 expansion is performed on each of the patterns before looking for |
|
|
533 matching file names. |
|
|
534 @end deftypefn |
|
|
535 |
|
2496
|
536 @deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string}) |
|
|
537 Return 1 or zero for each element of @var{string} that matches any of |
|
|
538 the elements of the string array @var{pattern}, using the rules of |
|
|
539 filename pattern matching. |
|
|
540 @end deftypefn |
|
|
541 |
|
2670
|
542 @deftypefn {Built-in Function} {} file_in_path (@var{path}, @var{file}) |
|
|
543 Return the absolute name name of @var{file} if it can be found in |
|
|
544 @var{path}. The value of @var{path} should be a colon-separated list of |
|
|
545 directories in the format described for the built-in variable |
|
|
546 @code{LOADPATH}. |
|
2449
|
547 |
|
2670
|
548 If the file cannot be found in the path, an empty matrix is returned. |
|
|
549 For example, |
|
2333
|
550 |
|
2670
|
551 @example |
|
|
552 octave:13> file_in_path (LOADPATH, "nargchk.m") |
|
|
553 ans = "@value{OCTAVEHOME}/share/octave/2.0/m/general/nargchk.m" |
|
|
554 @end example |
|
2475
|
555 @end deftypefn |
|
|
556 |
|
2670
|
557 @deftypefn {Built-in Function} {} tilde_expand (@var{string}) |
|
|
558 Performs tilde expansion on @var{string}. |
|
2449
|
559 @end deftypefn |
|
|
560 |
|
2670
|
561 @node Controlling Subprocesses, Process ID Information, Filesystem Utilities, System Utilities |
|
|
562 @section Controlling Subprocesses |
|
2653
|
563 |
|
2670
|
564 Octave includes some high-level commands like @code{system} and |
|
|
565 @code{popen} for starting subprocesses. If you want to run another |
|
|
566 program to perform some task and then look at its output, you will |
|
|
567 probably want to use these functions. |
|
2653
|
568 |
|
2670
|
569 Octave also provides several very low-level Unix-like functions which |
|
|
570 can also be used for starting subprocesses, but you should probably only |
|
|
571 use them if you can't find any way to do what you need with the |
|
|
572 higher-level functions. |
|
2449
|
573 |
|
|
574 @deftypefn {Built-in Function} {} system (@var{string}, @var{return_output}, @var{type}) |
|
|
575 Execute a shell command specified by @var{string}. The second argument is optional. |
|
|
576 If @var{type} is @code{"async"}, the process is started in the |
|
|
577 background and the process id of the child proces is returned |
|
|
578 immediately. Otherwise, the process is started, and Octave waits until |
|
|
579 it exits. If @var{type} argument is omitted, a value of @code{"sync"} |
|
|
580 is assumed. |
|
|
581 |
|
|
582 If two input arguments are given (the actual value of |
|
|
583 @var{return_output} is irrelevant) and the subprocess is started |
|
|
584 synchronously, or if @var{system} is called with one input argument and |
|
|
585 one or more output arguments, the output from the command is returned. |
|
|
586 Otherwise, if the subprocess is executed synchronously, it's output is |
|
|
587 sent to the standard output. To send the output of a command executed |
|
|
588 with @var{system} through the pager, use a command like |
|
2333
|
589 |
|
|
590 @example |
|
2449
|
591 disp (system (cmd, 1)); |
|
2333
|
592 @end example |
|
|
593 |
|
|
594 @noindent |
|
2449
|
595 or |
|
2333
|
596 |
|
|
597 @example |
|
2449
|
598 printf ("%s\n", system (cmd, 1)); |
|
2333
|
599 @end example |
|
|
600 |
|
|
601 The @code{system} function can return two values. The first is any |
|
|
602 output from the command that was written to the standard output stream, |
|
|
603 and the second is the output status of the command. For example, |
|
|
604 |
|
|
605 @example |
|
|
606 [output, status] = system ("echo foo; exit 2"); |
|
|
607 @end example |
|
|
608 |
|
|
609 @noindent |
|
|
610 will set the variable @code{output} to the string @samp{foo}, and the |
|
|
611 variable @code{status} to the integer @samp{2}. |
|
2449
|
612 @end deftypefn |
|
2333
|
613 |
|
2670
|
614 @deftypefn {Built-in Function} {fid =} popen (@var{command}, @var{mode}) |
|
|
615 Open a pipe to a subprocess. |
|
|
616 @end deftypefn |
|
|
617 |
|
|
618 @deftypefn {Built-in Function} {} pclose (@var{fid}) |
|
|
619 Close a pipe from a subprocess. |
|
|
620 @end deftypefn |
|
|
621 |
|
|
622 @deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) |
|
|
623 Start a subprocess with 2-way communication. |
|
|
624 @end deftypefn |
|
|
625 |
|
2449
|
626 @defvr {Built-in Variable} EXEC_PATH |
|
|
627 The variable @code{EXEC_PATH} is a colon separated list of directories |
|
|
628 to search when executing subprograms. Its initial value is taken from |
|
|
629 the environment variable @code{OCTAVE_EXEC_PATH} (if it exists) or |
|
|
630 @code{PATH}, but that value can be overridden by the the command line |
|
|
631 argument @code{--exec-path PATH}, or by setting the value of |
|
|
632 @code{EXEC_PATH} in a startup script. If the value of @code{EXEC_PATH} |
|
|
633 begins (ends) with a colon, the directories |
|
2535
|
634 |
|
|
635 @example |
|
|
636 OCTAVE_HOME/libexec/octave/site/exec/ARCH |
|
|
637 OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH |
|
|
638 OCTAVE_HOME/bin |
|
|
639 @end example |
|
|
640 |
|
|
641 @noindent |
|
|
642 are prepended (appended) to @code{EXEC_PATH}, where @code{OCTAVE_HOME} |
|
|
643 is the top-level directory where all of Octave is installed |
|
|
644 (@file{/usr/local} by default). If you don't specify a value for |
|
|
645 @code{EXEC_PATH} explicitly, these special directories are prepended to |
|
|
646 your shell path. |
|
2449
|
647 @end defvr |
|
2333
|
648 |
|
2670
|
649 In most cases, the following functions simply decode their arguments and |
|
|
650 make the corresponding Unix system calls. For a complete example of how |
|
|
651 they can be used, look at the definition of the function @code{popen2}. |
|
|
652 |
|
|
653 @deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} fork () |
|
|
654 Create a copy of the current process. |
|
|
655 |
|
|
656 Fork can return one of the following values: |
|
|
657 |
|
|
658 @table @asis |
|
|
659 @item > 0 |
|
|
660 You are in the parent process. The value returned from @code{fork} is |
|
|
661 the process id of the child process. You should probably arrange to |
|
|
662 wait for any child processes to exit. |
|
|
663 |
|
|
664 @item 0 |
|
|
665 You are in the child process. You can call @code{exec} to start another |
|
|
666 process. If that fails, you should probably call @code{exit}. |
|
|
667 |
|
|
668 @item < 0 |
|
|
669 The call to @code{fork} failed for some reason. You must take evasive |
|
|
670 action. A system dependent error message will be waiting in @var{msg}. |
|
|
671 @end table |
|
|
672 @end deftypefn |
|
|
673 |
|
|
674 @deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} exec (@var{file}, @var{args}) |
|
|
675 Replace current process with a new process. Calling @code{exec} without |
|
|
676 first calling @code{fork} will terminate your current Octave process and |
|
|
677 replace it with the program named by @var{file}. For example, |
|
|
678 |
|
|
679 @example |
|
|
680 exec ("ls" "-l") |
|
|
681 @end example |
|
|
682 |
|
|
683 @noindent |
|
|
684 will run @code{ls} and return you to your shell prompt. |
|
|
685 |
|
|
686 If successful, @code{exec} does not return. If @code{exec} does return, |
|
|
687 @var{err} will be nonzero, and @var{msg} will contain a system-dependent |
|
|
688 error message. |
|
|
689 @end deftypefn |
|
|
690 |
|
|
691 @deftypefn {Built-in Function} {[@var{file_ids}, @var{err}, @var{msg}] =} pipe () |
|
|
692 Create a pipe and return the vector @var{file_ids}, which corresponding |
|
|
693 to the reading and writing ends of the pipe. |
|
|
694 |
|
|
695 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
696 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
697 system-dependent error message. |
|
|
698 @end deftypefn |
|
|
699 |
|
|
700 @deftypefn {Built-in Function} {[fid, msg] =} dup2 (@var{old}, @var{new}) |
|
|
701 Duplicate a file descriptor. |
|
|
702 |
|
|
703 If successful, @var{fid} is greater than zero and contains the new file |
|
|
704 ID. Otherwise, @var{fid} is negative and @var{msg} contains a |
|
|
705 system-dependent error message. |
|
|
706 @end deftypefn |
|
|
707 |
|
|
708 @deftypefn {Built-in Function} {[@var{pid}, @var{msg}] =} waitpid (@var{pid}, @var{options}) |
|
|
709 Wait for process @var{pid} to terminate. The @var{pid} argument can be: |
|
|
710 |
|
|
711 @table @asis |
|
|
712 @item -1 |
|
|
713 Wait for any child process. |
|
|
714 |
|
|
715 @item 0 |
|
|
716 Wait for any child process whose process group ID is equal to that of |
|
|
717 the Octave interpreter process. |
|
|
718 |
|
|
719 @item > 0 |
|
|
720 Wait for termination of the child process with ID @var{PID}. |
|
|
721 @end table |
|
|
722 |
|
|
723 The @var{options} argument can be: |
|
|
724 |
|
|
725 @table @asis |
|
|
726 @item 0 |
|
|
727 Wait until signal is received or a child process exits (this is the |
|
|
728 default if the @var{options} argument is missing). |
|
|
729 |
|
|
730 @item 1 |
|
|
731 Do not hang if status is not immediately available. |
|
|
732 |
|
|
733 @item 2 |
|
|
734 Report the status of any child processes that are stopped, and whose |
|
|
735 status has not yet been reported since they stopped. |
|
|
736 |
|
|
737 @item 3 |
|
|
738 Implies both 1 and 2. |
|
|
739 @end table |
|
|
740 |
|
|
741 If the returned value of @var{pid} is greater than 0, it is the process |
|
|
742 ID of the child process that exited. If an error occurs, @var{pid} will |
|
|
743 be less than zero and @var{msg} will contain a system-dependent error |
|
|
744 message. |
|
|
745 @end deftypefn |
|
|
746 |
|
|
747 @deftypefn {Built-in Function} {[@var{err}, @var{msg}] =} fcntl (@var{fid}, @var{request}, @var{arg}) |
|
|
748 Change the properties of the open file @var{fid}. The following values |
|
|
749 may be passed as @var{request}: |
|
|
750 |
|
|
751 @vtable @code |
|
|
752 @item F_DUPFD |
|
|
753 Return a duplicate file descriptor. |
|
|
754 |
|
|
755 @item F_GETFD |
|
|
756 Return the file descriptor flags for @var{fid}. |
|
|
757 |
|
|
758 @item F_SETFD |
|
|
759 Set the file descriptor flags for @var{fid}. |
|
|
760 |
|
|
761 @item F_GETFL |
|
|
762 Return the file status flags for @var{fid}. The following codes may be |
|
|
763 returned (some of the flags may be undefined on some systems). |
|
|
764 |
|
|
765 @vtable @code |
|
|
766 @item O_RDONLY |
|
|
767 Open for reading only. |
|
|
768 |
|
|
769 @item O_WRONLY |
|
|
770 Open for writing only. |
|
|
771 |
|
|
772 @item O_RDWR |
|
|
773 Open for reading and writing. |
|
|
774 |
|
|
775 @item O_APPEND |
|
|
776 Append on each write. |
|
|
777 |
|
|
778 @item O_NONBLOCK |
|
|
779 Nonblocking mode. |
|
|
780 |
|
|
781 @item O_SYNC |
|
|
782 Wait for writes to complete. |
|
|
783 |
|
|
784 @item O_ASYNC |
|
|
785 Asynchronous I/O. |
|
|
786 @end vtable |
|
|
787 |
|
|
788 @item F_SETFL |
|
|
789 Set the file status flags for @var{fid} to the value specified by |
|
|
790 @var{arg}. The only flags that can be changed are @code{O_APPEND} and |
|
|
791 @code{O_NONBLOCK}. |
|
|
792 @end vtable |
|
|
793 |
|
|
794 If successful, @var{err} is 0 and @var{msg} is an empty string. |
|
|
795 Otherwise, @var{err} is nonzero and @var{msg} contains a |
|
|
796 system-dependent error message. |
|
|
797 @end deftypefn |
|
|
798 |
|
|
799 @node Process ID Information, Environment Variables, Controlling Subprocesses, System Utilities |
|
|
800 @section Process, Group, and User IDs |
|
|
801 |
|
|
802 @deftypefn {Built-in Function} {} getpgrp () |
|
|
803 Return the process group id of the current process. |
|
|
804 @end deftypefn |
|
|
805 |
|
|
806 @deftypefn {Built-in Function} {} getpid () |
|
|
807 Return the process id of the current process. |
|
|
808 @end deftypefn |
|
|
809 |
|
|
810 @deftypefn {Built-in Function} {} getppid () |
|
|
811 Return the process id of the parent process. |
|
|
812 @end deftypefn |
|
|
813 |
|
|
814 @deftypefn {Built-in Function} {} geteuid () |
|
|
815 Return the effective user id of the current process. |
|
|
816 @end deftypefn |
|
|
817 |
|
|
818 @deftypefn {Built-in Function} {} getuid () |
|
|
819 Return the real user id of the current process. |
|
|
820 @end deftypefn |
|
|
821 |
|
|
822 @deftypefn {Built-in Function} {} getegid () |
|
|
823 Return the effective group id of the current process. |
|
|
824 @end deftypefn |
|
|
825 |
|
|
826 @deftypefn {Built-in Function} {} getgid () |
|
|
827 Return the real group id of the current process. |
|
|
828 @end deftypefn |
|
|
829 |
|
|
830 @node Environment Variables, Current Working Directory, Process ID Information, System Utilities |
|
|
831 @section Environemnt Variables |
|
|
832 |
|
2449
|
833 @deftypefn {Built-in Function} {} getenv (@var{var}) |
|
|
834 Returns the value of the environment variable @var{var}. For example, |
|
2333
|
835 |
|
|
836 @example |
|
|
837 getenv ("PATH") |
|
|
838 @end example |
|
|
839 |
|
|
840 @noindent |
|
|
841 returns a string containing the value of your path. |
|
2449
|
842 @end deftypefn |
|
2333
|
843 |
|
2449
|
844 @deftypefn {Built-in Function} {} putenv (@var{var}, @var{value}) |
|
|
845 Set the value of the environment variable @var{var} to @var{value}. |
|
|
846 @end deftypefn |
|
2333
|
847 |
|
2670
|
848 @node Current Working Directory, Password Database Functions, Environment Variables, System Utilities |
|
|
849 @section Current Working Directory |
|
2333
|
850 |
|
2449
|
851 @deffn {Command} cd dir |
|
|
852 @deffnx {Command} chdir dir |
|
|
853 Change the current working directory to @var{dir}. For example, |
|
2333
|
854 |
|
|
855 @example |
|
|
856 cd ~/octave |
|
|
857 @end example |
|
|
858 |
|
|
859 @noindent |
|
|
860 Changes the current working directory to @file{~/octave}. If the |
|
|
861 directory does not exist, an error message is printed and the working |
|
|
862 directory is not changed. |
|
2449
|
863 @end deffn |
|
2333
|
864 |
|
2449
|
865 @deftypefn {Built-in Function} {} pwd () |
|
|
866 Returns the current working directory. |
|
|
867 @end deftypefn |
|
2333
|
868 |
|
2449
|
869 @defvr {Built-in Variable} PWD |
|
|
870 The current working directory. The value of @code{PWD} is updated each |
|
|
871 time the current working directory is changed with the @samp{cd} |
|
|
872 command. |
|
|
873 @end defvr |
|
2333
|
874 |
|
2653
|
875 @deffn {Command} ls options |
|
|
876 @deffnx {Command} dir options |
|
2449
|
877 List directory contents. For example, |
|
2333
|
878 |
|
|
879 @example |
|
|
880 octave:13> ls -l |
|
|
881 total 12 |
|
|
882 -rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m |
|
|
883 -rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m |
|
|
884 @end example |
|
|
885 |
|
|
886 The @code{dir} and @code{ls} commands are implemented by calling your |
|
|
887 system's directory listing command, so the available options may vary |
|
|
888 from system to system. |
|
2449
|
889 @end deffn |
|
2333
|
890 |
|
2670
|
891 @node Password Database Functions, Group Database Functions, Current Working Directory, System Utilities |
|
2460
|
892 @section Password Database Functions |
|
|
893 |
|
|
894 Octave's password database functions return information in a structure |
|
|
895 with the following fields. |
|
|
896 |
|
|
897 @table @code |
|
|
898 @item name |
|
|
899 The user name. |
|
|
900 |
|
|
901 @item passwd |
|
|
902 The encrypted password, if available. |
|
|
903 |
|
|
904 @item uid |
|
|
905 The numeric user id. |
|
|
906 |
|
|
907 @item gid |
|
|
908 The numeric group id. |
|
|
909 |
|
|
910 @item gecos |
|
|
911 The GECOS field. |
|
|
912 |
|
|
913 @item dir |
|
|
914 The home directory. |
|
|
915 |
|
|
916 @item shell |
|
|
917 The initial shell. |
|
|
918 @end table |
|
|
919 |
|
2670
|
920 @deftypefn {Loadable Function} {} getpwent () |
|
|
921 Return a structure containing an entry from the password database, |
|
|
922 opening it if necessary. Once the end of the data has been reached, |
|
|
923 @code{getpwent} returns 0. |
|
2460
|
924 @end deftypefn |
|
|
925 |
|
2670
|
926 @deftypefn {Loadable Function} {} getpwuid (@var{uid}). |
|
|
927 Return a structure containing the first entry from the password database |
|
|
928 with the user ID @var{uid}. If the user ID does not exist in the |
|
|
929 database, @code{getpwuid} returns 0. |
|
2460
|
930 @end deftypefn |
|
|
931 |
|
2670
|
932 @deftypefn {Loadable Function} {} getpwnam (@var{name}) |
|
|
933 Return a structure containing the first entry from the password database |
|
|
934 with the user name @var{name}. If the user name does not exist in the |
|
|
935 database, @code{getpwname} returns 0. |
|
2460
|
936 @end deftypefn |
|
|
937 |
|
2465
|
938 @deftypefn {Loadable Function} {} setpwent () |
|
2460
|
939 Return the internal pointer to the beginning of the password database. |
|
|
940 @end deftypefn |
|
|
941 |
|
2465
|
942 @deftypefn {Loadable Function} {} endpwent () |
|
2460
|
943 Close the password database. |
|
|
944 @end deftypefn |
|
|
945 |
|
2475
|
946 @node Group Database Functions, System Information, Password Database Functions, System Utilities |
|
|
947 @section Group Database Functions |
|
|
948 |
|
|
949 Octave's group database functions return information in a structure |
|
|
950 with the following fields. |
|
|
951 |
|
|
952 @table @code |
|
|
953 @item name |
|
|
954 The user name. |
|
|
955 |
|
|
956 @item passwd |
|
|
957 The encrypted password, if available. |
|
|
958 |
|
|
959 @item gid |
|
|
960 The numeric group id. |
|
|
961 |
|
|
962 @item mem |
|
|
963 The members of the group. |
|
|
964 @end table |
|
|
965 |
|
|
966 @deftypefn {Loadable Function} {group_struct =} getgrent () |
|
|
967 Return an entry from the group database, opening it if necessary. |
|
|
968 Once the end of the data has been reached, @code{getgrent} returns 0. |
|
|
969 @end deftypefn |
|
|
970 |
|
|
971 @deftypefn {Loadable Function} {group_struct =} getgrgid (@var{gid}). |
|
|
972 Return the first entry from the group database with the group ID |
|
|
973 @var{gid}. If the group ID does not exist in the database, |
|
|
974 @code{getgrgid} returns 0. |
|
|
975 @end deftypefn |
|
|
976 |
|
|
977 @deftypefn {Loadable Function} {group_struct =} getgrnam (@var{name}) |
|
|
978 Return the first entry from the group database with the group name |
|
|
979 @var{name}. If the group name does not exist in the database, |
|
|
980 @code{getgrname} returns 0. |
|
|
981 @end deftypefn |
|
|
982 |
|
|
983 @deftypefn {Loadable Function} {} setgrent () |
|
|
984 Return the internal pointer to the beginning of the group database. |
|
|
985 @end deftypefn |
|
|
986 |
|
|
987 @deftypefn {Loadable Function} {} endgrent () |
|
|
988 Close the group database. |
|
|
989 @end deftypefn |
|
|
990 |
|
2670
|
991 @node System Information, , Group Database Functions, System Utilities |
|
2333
|
992 @section System Information |
|
|
993 |
|
2449
|
994 @deftypefn {Built-in Function} {} computer () |
|
|
995 Returns a string of the form @var{cpu}-@var{vendor}-@var{os} that |
|
|
996 identifies the kind of computer Octave is running on. For example, |
|
2333
|
997 |
|
|
998 @example |
|
|
999 octave:13> computer |
|
|
1000 sparc-sun-sunos4.1.2 |
|
|
1001 @end example |
|
2449
|
1002 @end deftypefn |
|
2333
|
1003 |
|
2449
|
1004 @deftypefn {Built-in Function} {} isieee () |
|
|
1005 Return 1 if your computer claims to conform to the IEEE standard for |
|
|
1006 floating point calculations. |
|
|
1007 @end deftypefn |
|
2333
|
1008 |
|
2449
|
1009 @deftypefn {Built-in Function} {} version () |
|
|
1010 Returns Octave's version number as a string. This is also the value of |
|
2670
|
1011 the built-in variable @code{OCTAVE_VERSION}. |
|
|
1012 @end deftypefn |
|
|
1013 |
|
|
1014 @defvr {Built-in Variable} OCTAVE_VERSION |
|
|
1015 The version number of Octave, as a string. |
|
|
1016 @end defvr |
|
|
1017 |
|
|
1018 @deftypefn {Built-in Function} {} octave_config_info () |
|
|
1019 Return a structure containing configuration and installation |
|
|
1020 information. |
|
2449
|
1021 @end deftypefn |
|
2333
|
1022 |
|
2465
|
1023 @deftypefn {Loadable Function} {} getrusage () |
|
2449
|
1024 Return a structure containing a number of statistics about the current |
|
|
1025 Octave process. Not all fields are available on all systems. If it is |
|
|
1026 not possible to get CPU time statistics, the CPU time slots are set to |
|
|
1027 zero. Other missing data are replaced by NaN. Here is a list of all |
|
|
1028 the possible fields that can be present in the structure returned by |
|
|
1029 @code{getrusage}: |
|
2333
|
1030 |
|
|
1031 @table @code |
|
|
1032 @item |
|
|
1033 @item idrss |
|
|
1034 Unshared data size. |
|
|
1035 |
|
|
1036 @item inblock |
|
|
1037 Number of block input operations. |
|
|
1038 |
|
|
1039 @item isrss |
|
|
1040 Unshared stack size. |
|
|
1041 |
|
|
1042 @item ixrss |
|
|
1043 Shared memory size. |
|
|
1044 |
|
|
1045 @item majflt |
|
|
1046 Number of major page faults. |
|
|
1047 |
|
|
1048 @item maxrss |
|
|
1049 Maximum data size. |
|
|
1050 |
|
|
1051 @item minflt |
|
|
1052 Number of minor page faults. |
|
|
1053 |
|
|
1054 @item msgrcv |
|
|
1055 Number of messages received. |
|
|
1056 |
|
|
1057 @item msgsnd |
|
|
1058 Number of messages sent. |
|
|
1059 |
|
|
1060 @item nivcsw |
|
|
1061 Number of involuntary context switches. |
|
|
1062 |
|
|
1063 @item nsignals |
|
|
1064 Number of signals received. |
|
|
1065 |
|
|
1066 @item nswap |
|
|
1067 Number of swaps. |
|
|
1068 |
|
|
1069 @item nvcsw |
|
|
1070 Number of voluntary context switches. |
|
|
1071 |
|
|
1072 @item oublock |
|
|
1073 Number of block output operations. |
|
|
1074 |
|
|
1075 @item stime |
|
|
1076 A structure containing the system CPU time used. The structure has the |
|
|
1077 elements @code{sec} (seconds) @code{usec} (microseconds). |
|
|
1078 |
|
|
1079 @item utime |
|
|
1080 A structure containing the user CPU time used. The structure has the |
|
|
1081 elements @code{sec} (seconds) @code{usec} (microseconds). |
|
|
1082 @end table |
|
2449
|
1083 @end deftypefn |
