|
2333
|
1 @c Copyright (C) 1996 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
2653
|
5 @node System Utilities, Programming Utilities, 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:: |
|
|
17 * Interacting with the OS:: |
|
2460
|
18 * Password Database Functions:: |
|
2475
|
19 * Group Database Functions:: |
|
2333
|
20 * System Information:: |
|
|
21 * Other Functions:: |
|
|
22 @end menu |
|
|
23 |
|
|
24 @node Timing Utilities, Filesystem Utilities, System Utilities, System Utilities |
|
|
25 @section Timing Utilities |
|
|
26 |
|
2465
|
27 @deftypefn {Loadable Function} {} time () |
|
2449
|
28 Return the current time as the number of seconds since the epoch. The |
|
|
29 epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan |
|
|
30 1970. |
|
|
31 @end deftypefn |
|
2333
|
32 |
|
2653
|
33 Several of Octave's time functions use a data structure for time that |
|
2333
|
34 includes the following elements: |
|
|
35 |
|
|
36 @table @code |
|
|
37 @item usec |
|
|
38 Microseconds after the second (0-999999). |
|
|
39 |
|
|
40 @item sec |
|
|
41 Seconds after the minute (0-61). This number can be 61 to account |
|
|
42 for leap seconds. |
|
|
43 |
|
|
44 @item min |
|
|
45 Minutes after the hour (0-59). |
|
|
46 |
|
|
47 @item hour |
|
|
48 Hours since midnight (0-23). |
|
|
49 |
|
|
50 @item mday |
|
|
51 Day of the month (1-31). |
|
|
52 |
|
|
53 @item mon |
|
|
54 Months since January (0-11). |
|
|
55 |
|
|
56 @item year |
|
|
57 Years since 1900. |
|
|
58 |
|
|
59 @item wday |
|
|
60 Days since Sunday (0-6). |
|
|
61 |
|
|
62 @item yday |
|
|
63 Days since January 1 (0-365). |
|
|
64 |
|
|
65 @item isdst |
|
|
66 Daylight Savings Time flag. |
|
|
67 |
|
|
68 @item zone |
|
|
69 Time zone. |
|
|
70 @end table |
|
|
71 |
|
2465
|
72 @deftypefn {Loadable Function} {} mktime (@var{time_struct}) |
|
2449
|
73 Convert a time structure to the number of seconds since the epoch. |
|
|
74 @end deftypefn |
|
2333
|
75 |
|
2465
|
76 @deftypefn {Loadable Function} {} localtime (@var{t}) |
|
2449
|
77 Given a value returned from time (or any nonnegative integer), |
|
|
78 return a time structure corresponding to the local time zone. |
|
|
79 @end deftypefn |
|
2333
|
80 |
|
2465
|
81 @deftypefn {Loadable Function} {} gmtime (@var{t}) |
|
2449
|
82 Given a value returned from time (or any nonnegative integer), |
|
|
83 return a time structure corresponding to CUT. |
|
|
84 @end deftypefn |
|
2333
|
85 |
|
2449
|
86 @deftypefn {Function File} {} asctime (@var{time_struct}) |
|
|
87 Convert a time structure to a string using the following five-field |
|
|
88 format: Thu Mar 28 08:40:14 1996. The function @code{ctime (time)} is |
|
|
89 equivalent to @code{asctime (localtime (time))}. |
|
|
90 @end deftypefn |
|
2333
|
91 |
|
2465
|
92 @deftypefn {Loadable Function} {} strftime (@var{time_struct}) |
|
2449
|
93 Format a time structure in a flexible way using @samp{%} substitutions |
|
|
94 similar to those in @code{printf}. Except where noted, substituted |
|
|
95 fields have a fixed size; numeric fields are padded if necessary. |
|
|
96 Padding is with zeros by default; for fields that display a single |
|
|
97 number, padding can be changed or inhibited by following the @samp{%} |
|
|
98 with one of the modifiers described below. Unknown field specifiers are |
|
|
99 copied as normal characters. All other characters are copied to the |
|
|
100 output without change. |
|
2333
|
101 |
|
|
102 Octave's @code{strftime} function supports a superset of the ANSI C |
|
|
103 field specifiers. |
|
|
104 |
|
|
105 @noindent |
|
|
106 Literal character fields: |
|
|
107 |
|
|
108 @table @code |
|
|
109 @item % |
|
|
110 % character. |
|
|
111 |
|
|
112 @item n |
|
|
113 Newline character. |
|
|
114 |
|
|
115 @item t |
|
|
116 Tab character. |
|
|
117 @end table |
|
|
118 |
|
|
119 @noindent |
|
|
120 Numeric modifiers (a nonstandard extension): |
|
|
121 |
|
|
122 @table @code |
|
2653
|
123 @item - (dash) |
|
2333
|
124 Do not pad the field. |
|
|
125 |
|
2653
|
126 @item _ (underscore) |
|
2333
|
127 Pad the field with spaces. |
|
|
128 @end table |
|
|
129 |
|
|
130 @noindent |
|
|
131 Time fields: |
|
|
132 |
|
|
133 @table @code |
|
|
134 @item %H |
|
|
135 Hour (00-23). |
|
|
136 |
|
|
137 @item %I |
|
|
138 Hour (01-12). |
|
|
139 |
|
|
140 @item %k |
|
|
141 Hour (0-23). |
|
|
142 |
|
|
143 @item %l |
|
|
144 Hour (1-12). |
|
|
145 |
|
|
146 @item %M |
|
|
147 Minute (00-59). |
|
|
148 |
|
|
149 @item %p |
|
|
150 Locale's AM or PM. |
|
|
151 |
|
|
152 @item %r |
|
|
153 Time, 12-hour (hh:mm:ss [AP]M). |
|
|
154 |
|
|
155 @item %R |
|
|
156 Time, 24-hour (hh:mm). |
|
|
157 |
|
|
158 @item %s |
|
|
159 Time in seconds since 00:00:00, Jan 1, 1970 (a nonstandard extension). |
|
|
160 |
|
|
161 @item %S |
|
|
162 Second (00-61). |
|
|
163 |
|
|
164 @item %T |
|
|
165 Time, 24-hour (hh:mm:ss). |
|
|
166 |
|
|
167 @item %X |
|
|
168 Locale's time representation (%H:%M:%S). |
|
|
169 |
|
|
170 @item %Z |
|
|
171 Time zone (EDT), or nothing if no time zone is determinable. |
|
|
172 @end table |
|
|
173 |
|
|
174 @noindent |
|
|
175 Date fields: |
|
|
176 |
|
|
177 @table @code |
|
|
178 @item %a |
|
|
179 Locale's abbreviated weekday name (Sun-Sat). |
|
|
180 |
|
|
181 @item %A |
|
|
182 Locale's full weekday name, variable length (Sunday-Saturday). |
|
|
183 |
|
|
184 @item %b |
|
|
185 Locale's abbreviated month name (Jan-Dec). |
|
|
186 |
|
|
187 @item %B |
|
|
188 Locale's full month name, variable length (January-December). |
|
|
189 |
|
|
190 @item %c |
|
|
191 Locale's date and time (Sat Nov 04 12:02:33 EST 1989). |
|
|
192 |
|
|
193 @item %C |
|
|
194 Century (00-99). |
|
|
195 |
|
|
196 @item %d |
|
|
197 Day of month (01-31). |
|
|
198 |
|
|
199 @item %e |
|
|
200 Day of month ( 1-31). |
|
|
201 |
|
|
202 @item %D |
|
|
203 Date (mm/dd/yy). |
|
|
204 |
|
|
205 @item %h |
|
|
206 Same as %b. |
|
|
207 |
|
|
208 @item %j |
|
|
209 Day of year (001-366). |
|
|
210 |
|
|
211 @item %m |
|
|
212 Month (01-12). |
|
|
213 |
|
|
214 @item %U |
|
|
215 Week number of year with Sunday as first day of week (00-53). |
|
|
216 |
|
|
217 @item %w |
|
|
218 Day of week (0-6). |
|
|
219 |
|
|
220 @item %W |
|
|
221 Week number of year with Monday as first day of week (00-53). |
|
|
222 |
|
|
223 @item %x |
|
|
224 Locale's date representation (mm/dd/yy). |
|
|
225 |
|
|
226 @item %y |
|
|
227 Last two digits of year (00-99). |
|
|
228 |
|
|
229 @item %Y |
|
|
230 Year (1970-). |
|
|
231 @end table |
|
2449
|
232 @end deftypefn |
|
2333
|
233 |
|
2449
|
234 @deftypefn {Function File} {} clock () |
|
|
235 Return a vector containing the current year, month (1-12), day (1-31), |
|
|
236 hour (0-23), minute (0-59) and second (0-61). For example, |
|
2333
|
237 |
|
|
238 @example |
|
|
239 octave:13> clock |
|
|
240 ans = |
|
|
241 |
|
|
242 1993 8 20 4 56 1 |
|
|
243 @end example |
|
|
244 |
|
|
245 The function clock is more accurate on systems that have the |
|
|
246 @code{gettimeofday} function. |
|
2449
|
247 @end deftypefn |
|
2333
|
248 |
|
2449
|
249 @deftypefn {Function File} {} date () |
|
|
250 Returns the date as a character string in the form DD-MMM-YY. For |
|
|
251 example, |
|
2333
|
252 |
|
|
253 @example |
|
|
254 octave:13> date |
|
|
255 ans = 20-Aug-93 |
|
|
256 @end example |
|
2449
|
257 @end deftypefn |
|
2333
|
258 |
|
2449
|
259 @deftypefn {Function File} {} etime (@var{t1}, @var{t2}) |
|
|
260 Return the difference (in seconds) between two time values returned from |
|
|
261 @code{clock}. For example: |
|
2333
|
262 |
|
|
263 @example |
|
|
264 t0 = clock (); |
|
|
265 # many computations later... |
|
|
266 elapsed_time = etime (clock (), t0); |
|
|
267 @end example |
|
|
268 |
|
|
269 @noindent |
|
|
270 will set the variable @code{elapsed_time} to the number of seconds since |
|
|
271 the variable @code{t0} was set. |
|
2449
|
272 @end deftypefn |
|
2333
|
273 |
|
2449
|
274 @deftypefn {Built-in Function} {[@var{total}, @var{user}, @var{system}] =} cputime (); |
|
|
275 Return the CPU time used by your Octave session. The first output is |
|
2333
|
276 the total time spent executing your process and is equal to the sum of |
|
|
277 second and third outputs, which are the number of CPU seconds spent |
|
|
278 executing in user mode and the number of CPU seconds spent executing in |
|
|
279 system mode, respectively. If your system does not have a way to report |
|
|
280 CPU time usage, @code{cputime} returns 0 for each of its output values. |
|
2653
|
281 Note that because Octave used some CPU time to start, it is reasonable |
|
|
282 to check to see if @code{cputime} works by checking to see if the total |
|
|
283 CPU time used is nonzero. |
|
2449
|
284 @end deftypefn |
|
2333
|
285 |
|
2449
|
286 @deftypefn {Function File} {} is_leap_year (@var{year}) |
|
|
287 Return 1 if the given year is a leap year and 0 otherwise. If no |
|
|
288 arguments are provided, @code{is_leap_year} will use the current year. |
|
|
289 For example, |
|
2333
|
290 |
|
|
291 @example |
|
|
292 octave:13> is_leap_year (2000) |
|
|
293 ans = 1 |
|
|
294 @end example |
|
2449
|
295 @end deftypefn |
|
2333
|
296 |
|
2653
|
297 @deftypefn {Function File} {} tic () |
|
|
298 @deftypefnx {Function File} {} toc () |
|
|
299 These functions set and check a wall-clock timer. For example, |
|
|
300 |
|
|
301 @example |
|
|
302 tic (); |
|
|
303 # many computations later... |
|
|
304 elapsed_time = toc (); |
|
|
305 @end example |
|
|
306 |
|
|
307 @noindent |
|
|
308 will set the variable @code{elapsed_time} to the number of seconds since |
|
|
309 the most recent call to the function @code{tic}. |
|
|
310 |
|
|
311 If you are more interested in the CPU time that your process used, you |
|
|
312 should use the @code{cputime} function instead. The @code{tic} and |
|
|
313 @code{toc} functions report the actual wall clock time that elapsed |
|
|
314 between the calls. This may include time spent processing other jobs or |
|
|
315 doing nothing at all. For example, |
|
|
316 |
|
|
317 @example |
|
|
318 @group |
|
|
319 tic (); sleep (5); toc () |
|
|
320 @result{} 5 |
|
|
321 t = cputime (); sleep (5); cputime () - t |
|
|
322 @result{} 0 |
|
|
323 @end group |
|
|
324 @end example |
|
|
325 |
|
|
326 @noindent |
|
|
327 (This example also illustrates that the CPU timer may have a fairly |
|
|
328 coarse resolution.) |
|
|
329 @end deftypefn |
|
|
330 |
|
2333
|
331 @node Filesystem Utilities, Interacting with the OS, Timing Utilities, System Utilities |
|
|
332 @section Filesystem Utilities |
|
|
333 |
|
|
334 Octave includes the following functions for renaming and deleting files, |
|
|
335 creating, deleting, and reading directories, and for getting information |
|
|
336 about the status of files. |
|
|
337 |
|
2449
|
338 @deftypefn {Built-in Function} {} rename (@var{from}, @var{to}) |
|
2333
|
339 Rename a file. |
|
2449
|
340 @end deftypefn |
|
2333
|
341 |
|
2449
|
342 @deftypefn {Built-in Function} {} unlink (@var{file}) |
|
2333
|
343 Delete a file. |
|
2449
|
344 @end deftypefn |
|
2333
|
345 |
|
2449
|
346 @deftypefn {Built-in Function} {} readdir (@var{dir}) |
|
2333
|
347 Returns names of files in the directory @var{dir} as an array of |
|
|
348 strings. |
|
2449
|
349 @end deftypefn |
|
2333
|
350 |
|
2449
|
351 @deftypefn {Built-in Function} {} mkdir (@var{dir}) |
|
|
352 Create a directory |
|
|
353 @end deftypefn |
|
2333
|
354 |
|
2449
|
355 @deftypefn {Built-in Function} {} rmdir (@var{dir}) |
|
|
356 Remove a directory. |
|
|
357 @end deftypefn |
|
|
358 |
|
2333
|
359 @c XXX FIXME XXX -- this needs to be explained, but I don't feel up to |
|
|
360 @c it just now... |
|
|
361 |
|
2449
|
362 @deftypefn {Built-in Function} {} umask (@var{mask}) |
|
|
363 Set permission mask for file creation. |
|
|
364 @end deftypefn |
|
|
365 |
|
|
366 @deftypefn {Built-in Function} {} stat (@var{file}) |
|
2333
|
367 Get information about a file. If @var{file} is a symbolic link, |
|
|
368 @code{stat} returns information about the file that the symbolic link |
|
|
369 references. |
|
2449
|
370 @end deftypefn |
|
2333
|
371 |
|
2449
|
372 @deftypefn {Built-in Function} {} lstat (@var{file}) |
|
2333
|
373 Get information about a symbolic link. If @var{file} is not a symbolic |
|
|
374 link, @code{lstat} is equivalent to @code{stat}. |
|
2449
|
375 @end deftypefn |
|
2333
|
376 |
|
2495
|
377 @deftypefn {Built-in Function} {} glob (@var{pattern}) |
|
|
378 Given an array of strings in @var{pattern}, return the list of file |
|
|
379 names that any of them, or an empty string if no patterns match. Tilde |
|
|
380 expansion is performed on each of the patterns before looking for |
|
|
381 matching file names. |
|
|
382 @end deftypefn |
|
|
383 |
|
2496
|
384 @deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string}) |
|
|
385 Return 1 or zero for each element of @var{string} that matches any of |
|
|
386 the elements of the string array @var{pattern}, using the rules of |
|
|
387 filename pattern matching. |
|
|
388 @end deftypefn |
|
|
389 |
|
2460
|
390 @node Interacting with the OS, Password Database Functions, Filesystem Utilities, System Utilities |
|
2333
|
391 @section Interacting with the OS |
|
|
392 |
|
2449
|
393 @deftypefn {Built-in Function} {} fork () |
|
|
394 Create a copy of the current process. |
|
|
395 @end deftypefn |
|
|
396 |
|
|
397 @deftypefn {Built-in Function} {} exec (@var{file}, @var{args}) |
|
|
398 Replace current process with a new process. |
|
|
399 @end deftypefn |
|
|
400 |
|
|
401 @deftypefn {Built-in Function} {fid =} dup2 (@var{old}, @var{new}) |
|
|
402 Duplicate a file descriptor. |
|
|
403 @end deftypefn |
|
|
404 |
|
|
405 @deftypefn {Built-in Function} {[@var{file_ids}, @var{status}] =} pipe () |
|
|
406 Create an interprocess channel. |
|
|
407 @end deftypefn |
|
|
408 |
|
|
409 @deftypefn {Built-in Function} {} fcntl (@var{fid}, @var{request}, @var{argument}) |
|
|
410 Control open file descriptors. |
|
|
411 |
|
|
412 @vtable @code |
|
|
413 @item F_DUPFD |
|
|
414 @item F_GETFD |
|
|
415 @item F_GETFL |
|
|
416 @item F_SETFD |
|
|
417 @item F_SETFL |
|
|
418 @item O_APPEND |
|
|
419 @item O_CREAT |
|
|
420 @item O_EXCL |
|
|
421 @item O_NONBLOCK |
|
|
422 @item O_RDONLY |
|
|
423 @item O_RDWR |
|
|
424 @item O_TRUNC |
|
|
425 @item O_WRONLY |
|
|
426 @end vtable |
|
|
427 @end deftypefn |
|
2333
|
428 |
|
2449
|
429 @deftypefn {Built-in Function} {} getpgrp () |
|
|
430 Return the process group id of the current process. |
|
|
431 @end deftypefn |
|
|
432 |
|
|
433 @deftypefn {Built-in Function} {} getpid () |
|
|
434 Return the process id of the current process. |
|
|
435 @end deftypefn |
|
|
436 |
|
|
437 @deftypefn {Built-in Function} {} getppid () |
|
|
438 Return the process id of the parent process. |
|
|
439 @end deftypefn |
|
|
440 |
|
2475
|
441 @deftypefn {Built-in Function} {} geteuid () |
|
|
442 Return the effective user id of the current process. |
|
|
443 @end deftypefn |
|
|
444 |
|
|
445 @deftypefn {Built-in Function} {} getuid () |
|
|
446 Return the real user id of the current process. |
|
|
447 @end deftypefn |
|
|
448 |
|
|
449 @deftypefn {Built-in Function} {} getegid () |
|
|
450 Return the effective group id of the current process. |
|
|
451 @end deftypefn |
|
|
452 |
|
|
453 @deftypefn {Built-in Function} {} getgid () |
|
|
454 Return the real group id of the current process. |
|
|
455 @end deftypefn |
|
|
456 |
|
2449
|
457 @deftypefn {Built-in Function} {} mkfifo |
|
|
458 Create a FIFO special file. |
|
|
459 @end deftypefn |
|
|
460 |
|
2653
|
461 @deftypefn {Built-in Function} {} waitpid (@var{pid}, @var{options}) |
|
|
462 Wait for process @var{pid} to terminate. The @var{pid} argument can be: |
|
|
463 |
|
|
464 @table @asis |
|
|
465 @item -1 |
|
|
466 Wait for any child process. |
|
|
467 |
|
|
468 @item 0 |
|
|
469 Wait for any child process whose process group ID is equal to that of |
|
|
470 the Octave interpreter process. |
|
|
471 |
|
|
472 @item > 0 |
|
|
473 Wait for termination of the child process with ID @var{PID}. |
|
|
474 @end table |
|
|
475 |
|
|
476 The @var{options} argument can be: |
|
|
477 |
|
|
478 @table @asis |
|
|
479 @item 0 |
|
|
480 Wait until signal is received or a child process exits (this is the |
|
|
481 default if the @var{options} argument is missing). |
|
|
482 |
|
|
483 @item 1 |
|
|
484 Do not hang if status is not immediately available. |
|
|
485 |
|
|
486 @item 2 |
|
|
487 Report the status of any child processes that are stopped, and whose |
|
|
488 status has not yet been reported since they stopped. |
|
|
489 |
|
|
490 @item 3 |
|
|
491 Implies both 1 and 2. |
|
|
492 @end table |
|
|
493 |
|
|
494 If the return value is greater than 0, it is the process ID of the child |
|
|
495 process that exited. If an error occurs, -1 is returned. |
|
2449
|
496 @end deftypefn |
|
2333
|
497 |
|
2449
|
498 @deftypefn {Built-in Function} {} atexit (@var{fcn}) |
|
|
499 Register function to be called when Octave exits. |
|
|
500 @end deftypefn |
|
|
501 |
|
|
502 @deftypefn {Built-in Function} {} system (@var{string}, @var{return_output}, @var{type}) |
|
|
503 Execute a shell command specified by @var{string}. The second argument is optional. |
|
|
504 If @var{type} is @code{"async"}, the process is started in the |
|
|
505 background and the process id of the child proces is returned |
|
|
506 immediately. Otherwise, the process is started, and Octave waits until |
|
|
507 it exits. If @var{type} argument is omitted, a value of @code{"sync"} |
|
|
508 is assumed. |
|
|
509 |
|
|
510 If two input arguments are given (the actual value of |
|
|
511 @var{return_output} is irrelevant) and the subprocess is started |
|
|
512 synchronously, or if @var{system} is called with one input argument and |
|
|
513 one or more output arguments, the output from the command is returned. |
|
|
514 Otherwise, if the subprocess is executed synchronously, it's output is |
|
|
515 sent to the standard output. To send the output of a command executed |
|
|
516 with @var{system} through the pager, use a command like |
|
2333
|
517 |
|
|
518 @example |
|
2449
|
519 disp (system (cmd, 1)); |
|
2333
|
520 @end example |
|
|
521 |
|
|
522 @noindent |
|
2449
|
523 or |
|
2333
|
524 |
|
|
525 @example |
|
2449
|
526 printf ("%s\n", system (cmd, 1)); |
|
2333
|
527 @end example |
|
|
528 |
|
|
529 The @code{system} function can return two values. The first is any |
|
|
530 output from the command that was written to the standard output stream, |
|
|
531 and the second is the output status of the command. For example, |
|
|
532 |
|
|
533 @example |
|
|
534 [output, status] = system ("echo foo; exit 2"); |
|
|
535 @end example |
|
|
536 |
|
|
537 @noindent |
|
|
538 will set the variable @code{output} to the string @samp{foo}, and the |
|
|
539 variable @code{status} to the integer @samp{2}. |
|
2449
|
540 @end deftypefn |
|
2333
|
541 |
|
2449
|
542 @defvr {Built-in Variable} EXEC_PATH |
|
|
543 The variable @code{EXEC_PATH} is a colon separated list of directories |
|
|
544 to search when executing subprograms. Its initial value is taken from |
|
|
545 the environment variable @code{OCTAVE_EXEC_PATH} (if it exists) or |
|
|
546 @code{PATH}, but that value can be overridden by the the command line |
|
|
547 argument @code{--exec-path PATH}, or by setting the value of |
|
|
548 @code{EXEC_PATH} in a startup script. If the value of @code{EXEC_PATH} |
|
|
549 begins (ends) with a colon, the directories |
|
2535
|
550 |
|
|
551 @example |
|
|
552 OCTAVE_HOME/libexec/octave/site/exec/ARCH |
|
|
553 OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH |
|
|
554 OCTAVE_HOME/bin |
|
|
555 @end example |
|
|
556 |
|
|
557 @noindent |
|
|
558 are prepended (appended) to @code{EXEC_PATH}, where @code{OCTAVE_HOME} |
|
|
559 is the top-level directory where all of Octave is installed |
|
|
560 (@file{/usr/local} by default). If you don't specify a value for |
|
|
561 @code{EXEC_PATH} explicitly, these special directories are prepended to |
|
|
562 your shell path. |
|
2449
|
563 @end defvr |
|
2333
|
564 |
|
2449
|
565 @deftypefn {Built-in Function} {} getenv (@var{var}) |
|
|
566 Returns the value of the environment variable @var{var}. For example, |
|
2333
|
567 |
|
|
568 @example |
|
|
569 getenv ("PATH") |
|
|
570 @end example |
|
|
571 |
|
|
572 @noindent |
|
|
573 returns a string containing the value of your path. |
|
2449
|
574 @end deftypefn |
|
2333
|
575 |
|
2449
|
576 @deftypefn {Built-in Function} {} putenv (@var{var}, @var{value}) |
|
|
577 Set the value of the environment variable @var{var} to @var{value}. |
|
|
578 @end deftypefn |
|
2333
|
579 |
|
2449
|
580 @deftypefn {Built-in Function} {} clc () |
|
|
581 @deftypefnx {Built-in Function} {} home () |
|
|
582 Clear the terminal screen and move the cursor to the upper left corner. |
|
|
583 @end deftypefn |
|
2333
|
584 |
|
2449
|
585 @deffn {Command} cd dir |
|
|
586 @deffnx {Command} chdir dir |
|
|
587 Change the current working directory to @var{dir}. For example, |
|
2333
|
588 |
|
|
589 @example |
|
|
590 cd ~/octave |
|
|
591 @end example |
|
|
592 |
|
|
593 @noindent |
|
|
594 Changes the current working directory to @file{~/octave}. If the |
|
|
595 directory does not exist, an error message is printed and the working |
|
|
596 directory is not changed. |
|
2449
|
597 @end deffn |
|
2333
|
598 |
|
2449
|
599 @deftypefn {Built-in Function} {} pwd () |
|
|
600 Returns the current working directory. |
|
|
601 @end deftypefn |
|
2333
|
602 |
|
2449
|
603 @defvr {Built-in Variable} PWD |
|
|
604 The current working directory. The value of @code{PWD} is updated each |
|
|
605 time the current working directory is changed with the @samp{cd} |
|
|
606 command. |
|
|
607 @end defvr |
|
2333
|
608 |
|
2653
|
609 @deffn {Command} ls options |
|
|
610 @deffnx {Command} dir options |
|
2449
|
611 List directory contents. For example, |
|
2333
|
612 |
|
|
613 @example |
|
|
614 octave:13> ls -l |
|
|
615 total 12 |
|
|
616 -rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m |
|
|
617 -rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m |
|
|
618 @end example |
|
|
619 |
|
|
620 The @code{dir} and @code{ls} commands are implemented by calling your |
|
|
621 system's directory listing command, so the available options may vary |
|
|
622 from system to system. |
|
2449
|
623 @end deffn |
|
2333
|
624 |
|
2475
|
625 @node Password Database Functions, Group Database Functions, Interacting with the OS, System Utilities |
|
2460
|
626 @section Password Database Functions |
|
|
627 |
|
|
628 Octave's password database functions return information in a structure |
|
|
629 with the following fields. |
|
|
630 |
|
|
631 @table @code |
|
|
632 @item name |
|
|
633 The user name. |
|
|
634 |
|
|
635 @item passwd |
|
|
636 The encrypted password, if available. |
|
|
637 |
|
|
638 @item uid |
|
|
639 The numeric user id. |
|
|
640 |
|
|
641 @item gid |
|
|
642 The numeric group id. |
|
|
643 |
|
|
644 @item gecos |
|
|
645 The GECOS field. |
|
|
646 |
|
|
647 @item dir |
|
|
648 The home directory. |
|
|
649 |
|
|
650 @item shell |
|
|
651 The initial shell. |
|
|
652 @end table |
|
|
653 |
|
2465
|
654 @deftypefn {Loadable Function} {passwd_struct =} getpwent () |
|
2460
|
655 Return an entry from the password database, opening it if necessary. |
|
|
656 Once the end of the data has been reached, @code{getpwent} returns 0. |
|
|
657 @end deftypefn |
|
|
658 |
|
2465
|
659 @deftypefn {Loadable Function} {passwd_struct =} getpwuid (@var{uid}). |
|
2460
|
660 Return the first entry from the password database with the user ID |
|
|
661 @var{uid}. If the user ID does not exist in the database, |
|
2462
|
662 @code{getpwuid} returns 0. |
|
2460
|
663 @end deftypefn |
|
|
664 |
|
2465
|
665 @deftypefn {Loadable Function} {passwd_struct =} getpwnam (@var{name}) |
|
2460
|
666 Return the first entry from the password database with the user name |
|
|
667 @var{name}. If the user name does not exist in the database, |
|
2462
|
668 @code{getpwname} returns 0. |
|
2460
|
669 @end deftypefn |
|
|
670 |
|
2465
|
671 @deftypefn {Loadable Function} {} setpwent () |
|
2460
|
672 Return the internal pointer to the beginning of the password database. |
|
|
673 @end deftypefn |
|
|
674 |
|
2465
|
675 @deftypefn {Loadable Function} {} endpwent () |
|
2460
|
676 Close the password database. |
|
|
677 @end deftypefn |
|
|
678 |
|
2475
|
679 @node Group Database Functions, System Information, Password Database Functions, System Utilities |
|
|
680 @section Group Database Functions |
|
|
681 |
|
|
682 Octave's group database functions return information in a structure |
|
|
683 with the following fields. |
|
|
684 |
|
|
685 @table @code |
|
|
686 @item name |
|
|
687 The user name. |
|
|
688 |
|
|
689 @item passwd |
|
|
690 The encrypted password, if available. |
|
|
691 |
|
|
692 @item gid |
|
|
693 The numeric group id. |
|
|
694 |
|
|
695 @item mem |
|
|
696 The members of the group. |
|
|
697 @end table |
|
|
698 |
|
|
699 @deftypefn {Loadable Function} {group_struct =} getgrent () |
|
|
700 Return an entry from the group database, opening it if necessary. |
|
|
701 Once the end of the data has been reached, @code{getgrent} returns 0. |
|
|
702 @end deftypefn |
|
|
703 |
|
|
704 @deftypefn {Loadable Function} {group_struct =} getgrgid (@var{gid}). |
|
|
705 Return the first entry from the group database with the group ID |
|
|
706 @var{gid}. If the group ID does not exist in the database, |
|
|
707 @code{getgrgid} returns 0. |
|
|
708 @end deftypefn |
|
|
709 |
|
|
710 @deftypefn {Loadable Function} {group_struct =} getgrnam (@var{name}) |
|
|
711 Return the first entry from the group database with the group name |
|
|
712 @var{name}. If the group name does not exist in the database, |
|
|
713 @code{getgrname} returns 0. |
|
|
714 @end deftypefn |
|
|
715 |
|
|
716 @deftypefn {Loadable Function} {} setgrent () |
|
|
717 Return the internal pointer to the beginning of the group database. |
|
|
718 @end deftypefn |
|
|
719 |
|
|
720 @deftypefn {Loadable Function} {} endgrent () |
|
|
721 Close the group database. |
|
|
722 @end deftypefn |
|
|
723 |
|
|
724 @node System Information, Other Functions, Group Database Functions, System Utilities |
|
2333
|
725 @section System Information |
|
|
726 |
|
2449
|
727 @deftypefn {Built-in Function} {} computer () |
|
|
728 Returns a string of the form @var{cpu}-@var{vendor}-@var{os} that |
|
|
729 identifies the kind of computer Octave is running on. For example, |
|
2333
|
730 |
|
|
731 @example |
|
|
732 octave:13> computer |
|
|
733 sparc-sun-sunos4.1.2 |
|
|
734 @end example |
|
2449
|
735 @end deftypefn |
|
2333
|
736 |
|
2449
|
737 @deftypefn {Built-in Function} {} isieee () |
|
|
738 Return 1 if your computer claims to conform to the IEEE standard for |
|
|
739 floating point calculations. |
|
|
740 @end deftypefn |
|
2333
|
741 |
|
2449
|
742 @deftypefn {Built-in Function} {} version () |
|
|
743 Returns Octave's version number as a string. This is also the value of |
|
|
744 the built-in variable @code{OCTAVE_VERSION}. @xref{Built-in Variables}. |
|
|
745 @end deftypefn |
|
2333
|
746 |
|
2465
|
747 @deftypefn {Loadable Function} {} getrusage () |
|
2449
|
748 Return a structure containing a number of statistics about the current |
|
|
749 Octave process. Not all fields are available on all systems. If it is |
|
|
750 not possible to get CPU time statistics, the CPU time slots are set to |
|
|
751 zero. Other missing data are replaced by NaN. Here is a list of all |
|
|
752 the possible fields that can be present in the structure returned by |
|
|
753 @code{getrusage}: |
|
2333
|
754 |
|
|
755 @table @code |
|
|
756 @item |
|
|
757 @item idrss |
|
|
758 Unshared data size. |
|
|
759 |
|
|
760 @item inblock |
|
|
761 Number of block input operations. |
|
|
762 |
|
|
763 @item isrss |
|
|
764 Unshared stack size. |
|
|
765 |
|
|
766 @item ixrss |
|
|
767 Shared memory size. |
|
|
768 |
|
|
769 @item majflt |
|
|
770 Number of major page faults. |
|
|
771 |
|
|
772 @item maxrss |
|
|
773 Maximum data size. |
|
|
774 |
|
|
775 @item minflt |
|
|
776 Number of minor page faults. |
|
|
777 |
|
|
778 @item msgrcv |
|
|
779 Number of messages received. |
|
|
780 |
|
|
781 @item msgsnd |
|
|
782 Number of messages sent. |
|
|
783 |
|
|
784 @item nivcsw |
|
|
785 Number of involuntary context switches. |
|
|
786 |
|
|
787 @item nsignals |
|
|
788 Number of signals received. |
|
|
789 |
|
|
790 @item nswap |
|
|
791 Number of swaps. |
|
|
792 |
|
|
793 @item nvcsw |
|
|
794 Number of voluntary context switches. |
|
|
795 |
|
|
796 @item oublock |
|
|
797 Number of block output operations. |
|
|
798 |
|
|
799 @item stime |
|
|
800 A structure containing the system CPU time used. The structure has the |
|
|
801 elements @code{sec} (seconds) @code{usec} (microseconds). |
|
|
802 |
|
|
803 @item utime |
|
|
804 A structure containing the user CPU time used. The structure has the |
|
|
805 elements @code{sec} (seconds) @code{usec} (microseconds). |
|
|
806 @end table |
|
2449
|
807 @end deftypefn |
|
2333
|
808 |
|
|
809 @node Other Functions, , System Information, System Utilities |
|
|
810 @section Other Functions |
|
|
811 |
|
2449
|
812 @c XXX FIXME XXX -- need to define tilde expansion. |
|
|
813 |
|
|
814 @deftypefn {Built-in Function} {} tilde_expand (@var{string}) |
|
|
815 Performs tilde expansion on @var{string}. |
|
|
816 @end deftypefn |
|
2333
|
817 |
|
2449
|
818 @deftypefn {Built-in Function} {} pause (@var{seconds}) |
|
|
819 Suspend the execution of the program. If invoked without any arguments, |
|
|
820 Octave waits until you type a character. With a numeric argument, it |
|
|
821 pauses for the given number of seconds. For example, the following |
|
|
822 statement prints a message and then waits 5 seconds before clearing the |
|
|
823 screen. |
|
2333
|
824 |
|
|
825 @example |
|
2449
|
826 @group |
|
|
827 fprintf (stderr, "wait please...\n"); |
|
|
828 pause (5); |
|
|
829 clc; |
|
|
830 @end group |
|
2333
|
831 @end example |
|
2449
|
832 @end deftypefn |
|
2653
|
833 |
|
|
834 @deftypefn {Built-in Function} {} sleep (@var{seconds}) |
|
|
835 Suspend the execution of the program. |
|
|
836 @end deftypefn |
|
|
837 |
|
|
838 @deftypefn {Built-in Function} {} usleep (@var{microseconds}) |
|
|
839 Suspend the execution of the program. |
|
|
840 @end deftypefn |
|
|
841 |
|
|
842 @c XXX FIXME XXX -- not really sure where these should go. |
|
|
843 |
|
|
844 @cindex exiting octave |
|
|
845 @cindex quitting octave |
|
|
846 |
|
|
847 @deftypefn {Built-in Function} {} exit (@var{status}) |
|
|
848 @deftypefnx {Built-in Function} {} quit (@var{status}) |
|
|
849 Exit the current Octave session. If the optional integer value |
|
|
850 @var{status} is supplied, pass that value to the operating system as the |
|
|
851 Octave's exit status. |
|
|
852 @end deftypefn |
