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