1Unix(3) OCaml library Unix(3)
2
6 Unix - Interface to the Unix system
7
9 Module Unix
10
12 Module Unix
13 : sig end
14 Interface to the Unix system
17 === Error report ===
26 type error =
28 | E2BIG (* Argument list too long *)
29 | EACCES (* Permission denied *)
30 | EAGAIN (* Resource temporarily unavailable; try again *)
31 | EBADF (* Bad file descriptor *)
32 | EBUSY (* Resource unavailable *)
33 | ECHILD (* No child process *)
34 | EDEADLK (* Resource deadlock would occur *)
35 | EDOM (* Domain error for math functions, etc. *)
36 | EEXIST (* File exists *)
37 | EFAULT (* Bad address *)
38 | EFBIG (* File too large *)
39 | EINTR (* Function interrupted by signal *)
40 | EINVAL (* Invalid argument *)
41 | EIO (* Hardware I/O error *)
42 | EISDIR (* Is a directory *)
43 | EMFILE (* Too many open files by the process *)
44 | EMLINK (* Too many links *)
45 | ENAMETOOLONG (* Filename too long *)
46 | ENFILE (* Too many open files in the system *)
47 | ENODEV (* No such device *)
48 | ENOENT (* No such file or directory *)
49 | ENOEXEC (* Not an executable file *)
50 | ENOLCK (* No locks available *)
51 | ENOMEM (* Not enough memory *)
52 | ENOSPC (* No space left on device *)
53 | ENOSYS (* Function not supported *)
54 | ENOTDIR (* Not a directory *)
55 | ENOTEMPTY (* Directory not empty *)
56 | ENOTTY (* Inappropriate I/O control operation *)
57 | ENXIO (* No such device or address *)
58 | EPERM (* Operation not permitted *)
59 | EPIPE (* Broken pipe *)
60 | ERANGE (* Result too large *)
61 | EROFS (* Read-only file system *)
62 | ESPIPE (* Invalid seek e.g. on a pipe *)
63 | ESRCH (* No such process *)
64 | EXDEV (* Invalid link *)
65 | EWOULDBLOCK (* Operation would block *)
66 | EINPROGRESS (* Operation now in progress *)
67 | EALREADY (* Operation already in progress *)
68 | ENOTSOCK (* Socket operation on non-socket *)
69 | EDESTADDRREQ (* Destination address required *)
70 | EMSGSIZE (* Message too long *)
71 | EPROTOTYPE (* Protocol wrong type for socket *)
72 | ENOPROTOOPT (* Protocol not available *)
73 | EPROTONOSUPPORT (* Protocol not supported *)
74 | ESOCKTNOSUPPORT (* Socket type not supported *)
75 | EOPNOTSUPP (* Operation not supported on socket *)
76 | EPFNOSUPPORT (* Protocol family not supported *)
77 | EAFNOSUPPORT (* Address family not supported by protocol family *)
78 | EADDRINUSE (* Address already in use *)
79 | EADDRNOTAVAIL (* Can't assign requested address *)
80 | ENETDOWN (* Network is down *)
81 | ENETUNREACH (* Network is unreachable *)
82 | ENETRESET (* Network dropped connection on reset *)
83 | ECONNABORTED (* Software caused connection abort *)
84 | ECONNRESET (* Connection reset by peer *)
85 | ENOBUFS (* No buffer space available *)
86 | EISCONN (* Socket is already connected *)
87 | ENOTCONN (* Socket is not connected *)
88 | ESHUTDOWN (* Can't send after socket shutdown *)
89 | ETOOMANYREFS (* Too many references: can't splice *)
90 | ETIMEDOUT (* Connection timed out *)
91 | ECONNREFUSED (* Connection refused *)
92 | EHOSTDOWN (* Host is down *)
93 | EHOSTUNREACH (* No route to host *)
94 | ELOOP (* Too many levels of symbolic links *)
95 | EOVERFLOW (* File size or position not representable *)
96 | EUNKNOWNERR of int (* Unknown error *)
97 The type of error codes. Errors defined in the POSIX standard and
100 additional errors from UNIX98 and BSD. All other errors are mapped to
101 EUNKNOWNERR.
102 exception Unix_error of error * string * string
107 Raised by the system calls below when an error is encountered. The
110 first component is the error code; the second component is the function
111 name; the third component is the string parameter to the function, if
112 it has one, or the empty string otherwise.
113 val error_message : error -> string
118 Return a string describing the given error code.
120 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
125 handle_unix_error f x applies f to x and returns the result. If the
128 exception Unix_error is raised, it prints a message describing the
129 error and exits with code 2.
130 === Access to the process environment ===
136 val environment : unit -> string array
139 Return the process environment, as an array of strings with the format
141 ``variable=value''.
142 val getenv : string -> string
147 Return the value associated to a variable in the process environment.
149 Raise Not_found if the variable is unbound. (This function is identi‐
150 cal to Sys.getenv .)
151 val putenv : string -> string -> unit
156 Unix.putenv name value sets the value associated to a variable in the
159 process environment. name is the name of the environment variable, and
160 value its new associated value.
161 === Process handling ===
167 type process_status =
169 | WEXITED of int (* The process terminated normally by exit ; the
170 argument is the return code. *)
171 | WSIGNALED of int (* The process was killed by a signal; the argu‐
172 ment is the signal number. *)
173 | WSTOPPED of int (* The process was stopped by a signal; the argu‐
174 ment is the signal number. *)
175 The termination status of a process.
178 type wait_flag =
182 | WNOHANG (* do not block if no child has died yet, but immediately
183 return with a pid equal to 0. *)
184 | WUNTRACED (* report also the children that receive stop signals. *)
185 Flags for Unix.waitpid .
188 val execv : string -> string array -> 'a
193 execv prog args execute the program in file prog , with the arguments
196 args , and the current process environment. These execv* functions
197 never return: on success, the current program is replaced by the new
198 one; on failure, a Unix.Unix_error exception is raised.
199 val execve : string -> string array -> string array -> 'a
204 Same as Unix.execv , except that the third argument provides the envi‐
206 ronment to the program executed.
207 val execvp : string -> string array -> 'a
212 Same as Unix.execv , except that the program is searched in the path.
214 val execvpe : string -> string array -> string array -> 'a
219 Same as Unix.execve , except that the program is searched in the path.
221 val fork : unit -> int
226 Fork a new process. The returned integer is 0 for the child process,
228 the pid of the child process for the parent process.
229 val wait : unit -> int * process_status
234 Wait until one of the children processes die, and return its pid and
236 termination status.
237 val waitpid : wait_flag list -> int -> int * process_status
242 Same as Unix.wait , but waits for the child process whose pid is given.
244 A pid of -1 means wait for any child. A pid of 0 means wait for any
245 child in the same process group as the current process. Negative pid
246 arguments represent process groups. The list of options indicates
247 whether waitpid should return immediately without waiting, or also
248 report stopped children.
249 val system : string -> process_status
254 Execute the given command, wait until it terminates, and return its
256 termination status. The string is interpreted by the shell /bin/sh and
257 therefore can contain redirections, quotes, variables, etc. The result
258 WEXITED 127 indicates that the shell couldn't be executed.
259 val getpid : unit -> int
264 Return the pid of the process.
266 val getppid : unit -> int
271 Return the pid of the parent process.
273 val nice : int -> int
278 Change the process priority. The integer argument is added to the
280 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
281 ties.) Return the new nice value.
282 === Basic file input/output ===
288 type file_descr
290 The abstract type of file descriptors.
293 val stdin : file_descr
298 File descriptor for standard input.
300 val stdout : file_descr
305 File descriptor for standard output.
307 val stderr : file_descr
312 File descriptor for standard error.
314 type open_flag =
318 | O_RDONLY (* Open for reading *)
319 | O_WRONLY (* Open for writing *)
320 | O_RDWR (* Open for reading and writing *)
321 | O_NONBLOCK (* Open in non-blocking mode *)
322 | O_APPEND (* Open for append *)
323 | O_CREAT (* Create if nonexistent *)
324 | O_TRUNC (* Truncate to 0 length if existing *)
325 | O_EXCL (* Fail if existing *)
326 | O_NOCTTY (* Don't make this dev a controlling tty *)
327 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
328 pletion' *)
329 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
330 pletion' *)
331 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
332 *)
333 The flags to Unix.openfile .
336 type file_perm = int
340 The type of file access rights, e.g. 0o640 is read and write for user,
343 read for group, none for others
344 val openfile : string -> open_flag list -> file_perm -> file_descr
349 Open the named file with the given flags. Third argument is the permis‐
351 sions to give to the file if it is created. Return a file descriptor on
352 the named file.
353 val close : file_descr -> unit
358 Close a file descriptor.
360 val read : file_descr -> string -> int -> int -> int
365 read fd buff ofs len reads len characters from descriptor fd , storing
368 them in string buff , starting at position ofs in string buff . Return
369 the number of characters actually read.
370 val write : file_descr -> string -> int -> int -> int
375 write fd buff ofs len writes len characters to descriptor fd , taking
378 them from string buff , starting at position ofs in string buff .
379 Return the number of characters actually written. write repeats the
380 writing operation until all characters have been written or an error
381 occurs.
382 val single_write : file_descr -> string -> int -> int -> int
387 Same as write , but attempts to write only once. Thus, if an error
389 occurs, single_write guarantees that no data has been written.
390 === Interfacing with the standard input/output library ===
396 val in_channel_of_descr : file_descr -> Pervasives.in_channel
399 Create an input channel reading from the given descriptor. The channel
401 is initially in binary mode; use set_binary_mode_in ic false if text
402 mode is desired.
403 val out_channel_of_descr : file_descr -> Pervasives.out_channel
408 Create an output channel writing on the given descriptor. The channel
410 is initially in binary mode; use set_binary_mode_out oc false if text
411 mode is desired.
412 val descr_of_in_channel : Pervasives.in_channel -> file_descr
417 Return the descriptor corresponding to an input channel.
419 val descr_of_out_channel : Pervasives.out_channel -> file_descr
424 Return the descriptor corresponding to an output channel.
426 === Seeking and truncating ===
432 type seek_command =
434 | SEEK_SET (* indicates positions relative to the beginning of the
435 file *)
436 | SEEK_CUR (* indicates positions relative to the current position *)
437 | SEEK_END (* indicates positions relative to the end of the file *)
438 Positioning modes for Unix.lseek .
441 val lseek : file_descr -> int -> seek_command -> int
446 Set the current position for a file descriptor
448 val truncate : string -> int -> unit
453 Truncates the named file to the given size.
455 val ftruncate : file_descr -> int -> unit
460 Truncates the file corresponding to the given descriptor to the given
462 size.
463 === File status ===
469 type file_kind =
471 | S_REG (* Regular file *)
472 | S_DIR (* Directory *)
473 | S_CHR (* Character device *)
474 | S_BLK (* Block device *)
475 | S_LNK (* Symbolic link *)
476 | S_FIFO (* Named pipe *)
477 | S_SOCK (* Socket *)
478 type stats = {
483 st_dev : int ; (* Device number *)
484 st_ino : int ; (* Inode number *)
485 st_kind : file_kind ; (* Kind of the file *)
486 st_perm : file_perm ; (* Access rights *)
487 st_nlink : int ; (* Number of links *)
488 st_uid : int ; (* User id of the owner *)
489 st_gid : int ; (* Group ID of the file's group *)
490 st_rdev : int ; (* Device minor number *)
491 st_size : int ; (* Size in bytes *)
492 st_atime : float ; (* Last access time *)
493 st_mtime : float ; (* Last modification time *)
494 st_ctime : float ; (* Last status change time *)
495 }
496 The informations returned by the Unix.stat calls.
499 val stat : string -> stats
504 Return the informations for the named file.
506 val lstat : string -> stats
511 Same as Unix.stat , but in case the file is a symbolic link, return the
513 informations for the link itself.
514 val fstat : file_descr -> stats
519 Return the informations for the file associated with the given descrip‐
521 tor.
522 === File operations on large files ===
528 module LargeFile : sig end
530 File operations on large files. This sub-module provides 64-bit vari‐
533 ants of the functions Unix.lseek (for positioning a file descriptor),
534 Unix.truncate and Unix.ftruncate (for changing the size of a file), and
535 Unix.stat , Unix.lstat and Unix.fstat (for obtaining information on
536 files). These alternate functions represent positions and sizes by
537 64-bit integers (type int64 ) instead of regular integers (type int ),
538 thus allowing operating on files whose sizes are greater than max_int .
539 === Operations on file names ===
545 val unlink : string -> unit
548 Removes the named file
550 val rename : string -> string -> unit
555 rename old new changes the name of a file from old to new .
558 val link : string -> string -> unit
563 link source dest creates a hard link named dest to the file named
566 source .
567 === File permissions and ownership ===
573 type access_permission =
575 | R_OK (* Read permission *)
576 | W_OK (* Write permission *)
577 | X_OK (* Execution permission *)
578 | F_OK (* File exists *)
579 Flags for the Unix.access call.
582 val chmod : string -> file_perm -> unit
587 Change the permissions of the named file.
589 val fchmod : file_descr -> file_perm -> unit
594 Change the permissions of an opened file.
596 val chown : string -> int -> int -> unit
601 Change the owner uid and owner gid of the named file.
603 val fchown : file_descr -> int -> int -> unit
608 Change the owner uid and owner gid of an opened file.
610 val umask : int -> int
615 Set the process's file mode creation mask, and return the previous
617 mask.
618 val access : string -> access_permission list -> unit
623 Check that the process has the given permissions over the named file.
625 Raise Unix_error otherwise.
626 === Operations on file descriptors ===
632 val dup : file_descr -> file_descr
635 Return a new file descriptor referencing the same file as the given
637 descriptor.
638 val dup2 : file_descr -> file_descr -> unit
643 dup2 fd1 fd2 duplicates fd1 to fd2 , closing fd2 if already opened.
646 val set_nonblock : file_descr -> unit
651 Set the ``non-blocking'' flag on the given descriptor. When the non-
653 blocking flag is set, reading on a descriptor on which there is tempo‐
654 rarily no data available raises the EAGAIN or EWOULDBLOCK error instead
655 of blocking; writing on a descriptor on which there is temporarily no
656 room for writing also raises EAGAIN or EWOULDBLOCK .
657 val clear_nonblock : file_descr -> unit
662 Clear the ``non-blocking'' flag on the given descriptor. See
664 Unix.set_nonblock .
665 val set_close_on_exec : file_descr -> unit
670 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
672 with the close-on-exec flag is automatically closed when the current
673 process starts another program with one of the exec functions.
674 val clear_close_on_exec : file_descr -> unit
679 Clear the ``close-on-exec'' flag on the given descriptor. See
681 Unix.set_close_on_exec .
682 === Directories ===
688 val mkdir : string -> file_perm -> unit
691 Create a directory with the given permissions.
693 val rmdir : string -> unit
698 Remove an empty directory.
700 val chdir : string -> unit
705 Change the process working directory.
707 val getcwd : unit -> string
712 Return the name of the current working directory.
714 val chroot : string -> unit
719 Change the process root directory.
721 type dir_handle
725 The type of descriptors over opened directories.
728 val opendir : string -> dir_handle
733 Open a descriptor on a directory
735 val readdir : dir_handle -> string
740 Return the next entry in a directory.
742 Raises End_of_file when the end of the directory has been reached.
744 val rewinddir : dir_handle -> unit
749 Reposition the descriptor to the beginning of the directory
751 val closedir : dir_handle -> unit
756 Close a directory descriptor.
758 === Pipes and redirections ===
764 val pipe : unit -> file_descr * file_descr
767 Create a pipe. The first component of the result is opened for reading,
769 that's the exit to the pipe. The second component is opened for writ‐
770 ing, that's the entrance to the pipe.
771 val mkfifo : string -> file_perm -> unit
776 Create a named pipe with the given permissions.
778 === High-level process and redirection management ===
784 val create_process : string -> string array -> file_descr -> file_descr
787 -> file_descr -> int
788 create_process prog args new_stdin new_stdout new_stderr forks a new
791 process that executes the program in file prog , with arguments args .
792 The pid of the new process is returned immediately; the new process
793 executes concurrently with the current process. The standard input and
794 outputs of the new process are connected to the descriptors new_stdin ,
795 new_stdout and new_stderr . Passing e.g. stdout for new_stdout pre‐
796 vents the redirection and causes the new process to have the same stan‐
797 dard output as the current process. The executable file prog is
798 searched in the path. The new process has the same environment as the
799 current process.
800 val create_process_env : string -> string array -> string array ->
805 file_descr -> file_descr -> file_descr -> int
806 create_process_env prog args env new_stdin new_stdout new_stderr works
809 as Unix.create_process , except that the extra argument env specifies
810 the environment passed to the program.
811 val open_process_in : string -> Pervasives.in_channel
816 High-level pipe and process management. This function runs the given
818 command in parallel with the program. The standard output of the com‐
819 mand is redirected to a pipe, which can be read via the returned input
820 channel. The command is interpreted by the shell /bin/sh (cf. system
821 ).
822 val open_process_out : string -> Pervasives.out_channel
827 Same as Unix.open_process_in , but redirect the standard input of the
829 command to a pipe. Data written to the returned output channel is sent
830 to the standard input of the command. Warning: writes on output chan‐
831 nels are buffered, hence be careful to call Pervasives.flush at the
832 right times to ensure correct synchronization.
833 val open_process : string -> Pervasives.in_channel * Perva‐
838 sives.out_channel
839 Same as Unix.open_process_out , but redirects both the standard input
841 and standard output of the command to pipes connected to the two
842 returned channels. The input channel is connected to the output of the
843 command, and the output channel to the input of the command.
844 val open_process_full : string -> string array -> Pervasives.in_channel
849 * Pervasives.out_channel * Pervasives.in_channel
850 Similar to Unix.open_process , but the second argument specifies the
852 environment passed to the command. The result is a triple of channels
853 connected respectively to the standard output, standard input, and
854 standard error of the command.
855 val close_process_in : Pervasives.in_channel -> process_status
860 Close channels opened by Unix.open_process_in , wait for the associated
862 command to terminate, and return its termination status.
863 val close_process_out : Pervasives.out_channel -> process_status
868 Close channels opened by Unix.open_process_out , wait for the associ‐
870 ated command to terminate, and return its termination status.
871 val close_process : Pervasives.in_channel * Pervasives.out_channel ->
876 process_status
877 Close channels opened by Unix.open_process , wait for the associated
879 command to terminate, and return its termination status.
880 val close_process_full : Pervasives.in_channel * Pervasives.out_channel
885 * Pervasives.in_channel -> process_status
886 Close channels opened by Unix.open_process_full , wait for the associ‐
888 ated command to terminate, and return its termination status.
889 === Symbolic links ===
895 val symlink : string -> string -> unit
898 symlink source dest creates the file dest as a symbolic link to the
901 file source .
902 val readlink : string -> string
907 Read the contents of a link.
909 === Polling ===
915 val select : file_descr list -> file_descr list -> file_descr list ->
918 float -> file_descr list * file_descr list * file_descr list
919 Wait until some input/output operations become possible on some chan‐
921 nels. The three list arguments are, respectively, a set of descriptors
922 to check for reading (first argument), for writing (second argument),
923 or for exceptional conditions (third argument). The fourth argument is
924 the maximal timeout, in seconds; a negative fourth argument means no
925 timeout (unbounded wait). The result is composed of three sets of
926 descriptors: those ready for reading (first component), ready for writ‐
927 ing (second component), and over which an exceptional condition is
928 pending (third component).
929 === Locking ===
935 type lock_command =
937 | F_ULOCK (* Unlock a region *)
938 | F_LOCK (* Lock a region for writing, and block if already locked *)
939 | F_TLOCK (* Lock a region for writing, or fail if already locked *)
940 | F_TEST (* Test a region for other process locks *)
941 | F_RLOCK (* Lock a region for reading, and block if already locked
942 *)
943 | F_TRLOCK (* Lock a region for reading, or fail if already locked *)
944 Commands for Unix.lockf .
947 val lockf : file_descr -> lock_command -> int -> unit
952 lockf fd cmd size puts a lock on a region of the file opened as fd .
955 The region starts at the current read/write position for fd (as set by
956 Unix.lseek ), and extends size bytes forward if size is positive, size
957 bytes backwards if size is negative, or to the end of the file if size
958 is zero. A write lock prevents any other process from acquiring a read
959 or write lock on the region. A read lock prevents any other process
960 from acquiring a write lock on the region, but lets other processes
961 acquire read locks on it.
962 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
964 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
965 read lock on the specified region. If one or several locks put by
966 another process prevent the current process from acquiring the lock,
967 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
968 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
969 whatever locks the current process has on the specified region.
970 Finally, the F_TEST command tests whether a write lock can be acquired
971 on the specified region, without actually putting a lock. It returns
972 immediately if successful, or fails otherwise.
973 === Signals Note: installation of signal handlers is performed via the
979 functions Sys.signal and Sys.set_signal. ===
980 val kill : int -> int -> unit
983 kill pid sig sends signal number sig to the process with id pid .
986 type sigprocmask_command =
990 | SIG_SETMASK
991 | SIG_BLOCK
992 | SIG_UNBLOCK
993 val sigprocmask : sigprocmask_command -> int list -> int list
999 sigprocmask cmd sigs changes the set of blocked signals. If cmd is
1002 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1003 cmd is SIG_BLOCK , the signals in sigs are added to the set of blocked
1004 signals. If cmd is SIG_UNBLOCK , the signals in sigs are removed from
1005 the set of blocked signals. sigprocmask returns the set of previously
1006 blocked signals.
1007 val sigpending : unit -> int list
1012 Return the set of blocked signals that are currently pending.
1014 val sigsuspend : int list -> unit
1019 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1022 for a non-ignored, non-blocked signal to be delivered. On return, the
1023 blocked signals are reset to their initial value.
1024 val pause : unit -> unit
1029 Wait until a non-ignored, non-blocked signal is delivered.
1031 === Time functions ===
1037 type process_times = {
1039 tms_utime : float ; (* User time for the process *)
1040 tms_stime : float ; (* System time for the process *)
1041 tms_cutime : float ; (* User time for the children processes *)
1042 tms_cstime : float ; (* System time for the children processes *)
1043 }
1044 The execution times (CPU times) of a process.
1047 type tm = {
1051 tm_sec : int ; (* Seconds 0..60 *)
1052 tm_min : int ; (* Minutes 0..59 *)
1053 tm_hour : int ; (* Hours 0..23 *)
1054 tm_mday : int ; (* Day of month 1..31 *)
1055 tm_mon : int ; (* Month of year 0..11 *)
1056 tm_year : int ; (* Year - 1900 *)
1057 tm_wday : int ; (* Day of week (Sunday is 0) *)
1058 tm_yday : int ; (* Day of year 0..365 *)
1059 tm_isdst : bool ; (* Daylight time savings in effect *)
1060 }
1061 The type representing wallclock time and calendar date.
1064 val time : unit -> float
1069 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1071 val gettimeofday : unit -> float
1076 Same as Unix.time , but with resolution better than 1 second.
1078 val gmtime : float -> tm
1083 Convert a time in seconds, as returned by Unix.time , into a date and a
1085 time. Assumes UTC (Coordinated Universal Time), also known as GMT.
1086 val localtime : float -> tm
1091 Convert a time in seconds, as returned by Unix.time , into a date and a
1093 time. Assumes the local time zone.
1094 val mktime : tm -> float * tm
1099 Convert a date and time, specified by the tm argument, into a time in
1101 seconds, as returned by Unix.time . The tm_isdst , tm_wday and tm_yday
1102 fields of tm are ignored. Also return a normalized copy of the given
1103 tm record, with the tm_wday , tm_yday , and tm_isdst fields recomputed
1104 from the other fields, and the other fields normalized (so that, e.g.,
1105 40 October is changed into 9 November). The tm argument is interpreted
1106 in the local time zone.
1107 val alarm : int -> int
1112 Schedule a SIGALRM signal after the given number of seconds.
1114 val sleep : int -> unit
1119 Stop execution for the given number of seconds.
1121 val times : unit -> process_times
1126 Return the execution times of the process.
1128 val utimes : string -> float -> float -> unit
1133 Set the last access time (second arg) and last modification time (third
1135 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1136 1, 1970.
1137 type interval_timer =
1141 | ITIMER_REAL (* decrements in real time, and sends the signal
1142 SIGALRM when expired. *)
1143 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1144 SIGVTALRM when expired. *)
1145 | ITIMER_PROF (* (for profiling) decrements both when the process is
1146 running and when the system is running on behalf of the process; it
1147 sends SIGPROF when expired. *)
1148 The three kinds of interval timers.
1151 type interval_timer_status = {
1155 it_interval : float ; (* Period *)
1156 it_value : float ; (* Current value of the timer *)
1157 }
1158 The type describing the status of an interval timer
1161 val getitimer : interval_timer -> interval_timer_status
1166 Return the current status of the given interval timer.
1168 val setitimer : interval_timer -> interval_timer_status -> inter‐
1173 val_timer_status
1174 setitimer t s sets the interval timer t and returns its previous sta‐
1177 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1178 is the time to the next timer expiration; s.it_interval , if nonzero,
1179 specifies a value to be used in reloading it_value when the timer
1180 expires. Setting s.it_value to zero disable the timer. Setting
1181 s.it_interval to zero causes the timer to be disabled after its next
1182 expiration.
1183 === User id, group id ===
1189 val getuid : unit -> int
1192 Return the user id of the user executing the process.
1194 val geteuid : unit -> int
1199 Return the effective user id under which the process runs.
1201 val setuid : int -> unit
1206 Set the real user id and effective user id for the process.
1208 val getgid : unit -> int
1213 Return the group id of the user executing the process.
1215 val getegid : unit -> int
1220 Return the effective group id under which the process runs.
1222 val setgid : int -> unit
1227 Set the real group id and effective group id for the process.
1229 val getgroups : unit -> int array
1234 Return the list of groups to which the user executing the process
1236 belongs.
1237 type passwd_entry = {
1241 pw_name : string ;
1242 pw_passwd : string ;
1243 pw_uid : int ;
1244 pw_gid : int ;
1245 pw_gecos : string ;
1246 pw_dir : string ;
1247 pw_shell : string ;
1248 }
1249 Structure of entries in the passwd database.
1252 type group_entry = {
1256 gr_name : string ;
1257 gr_passwd : string ;
1258 gr_gid : int ;
1259 gr_mem : string array ;
1260 }
1261 Structure of entries in the groups database.
1264 val getlogin : unit -> string
1269 Return the login name of the user executing the process.
1271 val getpwnam : string -> passwd_entry
1276 Find an entry in passwd with the given name, or raise Not_found .
1278 val getgrnam : string -> group_entry
1283 Find an entry in group with the given name, or raise Not_found .
1285 val getpwuid : int -> passwd_entry
1290 Find an entry in passwd with the given user id, or raise Not_found .
1292 val getgrgid : int -> group_entry
1297 Find an entry in group with the given group id, or raise Not_found .
1299 === Internet addresses ===
1305 type inet_addr
1307 The abstract type of Internet addresses.
1310 val inet_addr_of_string : string -> inet_addr
1315 Conversion from the printable representation of an Internet address to
1317 its internal representation. The argument string consists of 4 numbers
1318 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1319 8 numbers separated by colons for IPv6 addresses. Raise Failure when
1320 given a string that does not match these formats.
1321 val string_of_inet_addr : inet_addr -> string
1326 Return the printable representation of the given Internet address. See
1328 Unix.inet_addr_of_string for a description of the printable representa‐
1329 tion.
1330 val inet_addr_any : inet_addr
1335 A special IPv4 address, for use only with bind , representing all the
1337 Internet addresses that the host machine possesses.
1338 val inet_addr_loopback : inet_addr
1343 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1345 val inet6_addr_any : inet_addr
1350 A special IPv6 address, for use only with bind , representing all the
1352 Internet addresses that the host machine possesses.
1353 val inet6_addr_loopback : inet_addr
1358 A special IPv6 address representing the host machine ( ::1 ).
1360 === Sockets ===
1366 type socket_domain =
1368 | PF_UNIX (* Unix domain *)
1369 | PF_INET (* Internet domain (IPv4) *)
1370 | PF_INET6 (* Internet domain (IPv6) *)
1371 The type of socket domains.
1374 type socket_type =
1378 | SOCK_STREAM (* Stream socket *)
1379 | SOCK_DGRAM (* Datagram socket *)
1380 | SOCK_RAW (* Raw socket *)
1381 | SOCK_SEQPACKET (* Sequenced packets socket *)
1382 The type of socket kinds, specifying the semantics of communications.
1385 type sockaddr =
1389 | ADDR_UNIX of string
1390 | ADDR_INET of inet_addr * int (* The type of socket addresses.
1391 ADDR_UNIX name is a socket address in the Unix domain; name is a file
1392 name in the file system. ADDR_INET(addr,port) is a socket address in
1393 the Internet domain; addr is the Internet address of the machine, and
1394 port is the port number. *)
1395 val socket : socket_domain -> socket_type -> int -> file_descr
1401 Create a new socket in the given domain, and with the given kind. The
1403 third argument is the protocol type; 0 selects the default protocol for
1404 that kind of sockets.
1405 val domain_of_sockaddr : sockaddr -> socket_domain
1410 Return the socket domain adequate for the given socket address.
1412 val socketpair : socket_domain -> socket_type -> int -> file_descr *
1417 file_descr
1418 Create a pair of unnamed sockets, connected together.
1420 val accept : file_descr -> file_descr * sockaddr
1425 Accept connections on the given socket. The returned descriptor is a
1427 socket connected to the client; the returned address is the address of
1428 the connecting client.
1429 val bind : file_descr -> sockaddr -> unit
1434 Bind a socket to an address.
1436 val connect : file_descr -> sockaddr -> unit
1441 Connect a socket to an address.
1443 val listen : file_descr -> int -> unit
1448 Set up a socket for receiving connection requests. The integer argument
1450 is the maximal number of pending requests.
1451 type shutdown_command =
1455 | SHUTDOWN_RECEIVE (* Close for receiving *)
1456 | SHUTDOWN_SEND (* Close for sending *)
1457 | SHUTDOWN_ALL (* Close both *)
1458 The type of commands for shutdown .
1461 val shutdown : file_descr -> shutdown_command -> unit
1466 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
1468 reads on the other end of the connection to return an end-of-file con‐
1469 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
1470 tion to return a closed pipe condition ( SIGPIPE signal).
1471 val getsockname : file_descr -> sockaddr
1476 Return the address of the given socket.
1478 val getpeername : file_descr -> sockaddr
1483 Return the address of the host connected to the given socket.
1485 type msg_flag =
1489 | MSG_OOB
1490 | MSG_DONTROUTE
1491 | MSG_PEEK (* The flags for Unix.recv , Unix.recvfrom , Unix.send and
1492 Unix.sendto . *)
1493 val recv : file_descr -> string -> int -> int -> msg_flag list -> int
1499 Receive data from a connected socket.
1501 val recvfrom : file_descr -> string -> int -> int -> msg_flag list ->
1506 int * sockaddr
1507 Receive data from an unconnected socket.
1509 val send : file_descr -> string -> int -> int -> msg_flag list -> int
1514 Send data over a connected socket.
1516 val sendto : file_descr -> string -> int -> int -> msg_flag list ->
1521 sockaddr -> int
1522 Send data over an unconnected socket.
1524 === Socket options ===
1530 type socket_bool_option =
1532 | SO_DEBUG (* Record debugging information *)
1533 | SO_BROADCAST (* Permit sending of broadcast messages *)
1534 | SO_REUSEADDR (* Allow reuse of local addresses for bind *)
1535 | SO_KEEPALIVE (* Keep connection active *)
1536 | SO_DONTROUTE (* Bypass the standard routing algorithms *)
1537 | SO_OOBINLINE (* Leave out-of-band data in line *)
1538 | SO_ACCEPTCONN (* Report whether socket listening is enabled *)
1539 The socket options that can be consulted with Unix.getsockopt and modi‐
1542 fied with Unix.setsockopt . These options have a boolean ( true /
1543 false ) value.
1544 type socket_int_option =
1548 | SO_SNDBUF (* Size of send buffer *)
1549 | SO_RCVBUF (* Size of received buffer *)
1550 | SO_ERROR (* Report the error status and clear it *)
1551 | SO_TYPE (* Report the socket type *)
1552 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
1553 tions *)
1554 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
1555 tions *)
1556 The socket options that can be consulted with Unix.getsockopt_int and
1559 modified with Unix.setsockopt_int . These options have an integer
1560 value.
1561 type socket_optint_option =
1565 | SO_LINGER (* Whether to linger on closed connections that have data
1566 present, and for how long (in seconds) *)
1567 The socket options that can be consulted with Unix.getsockopt_optint
1570 and modified with Unix.setsockopt_optint . These options have a value
1571 of type int option , with None meaning ``disabled''.
1572 type socket_float_option =
1576 | SO_RCVTIMEO (* Timeout for input operations *)
1577 | SO_SNDTIMEO (* Timeout for output operations *)
1578 The socket options that can be consulted with Unix.getsockopt_float and
1581 modified with Unix.setsockopt_float . These options have a floating-
1582 point value representing a time in seconds. The value 0 means infinite
1583 timeout.
1584 val getsockopt : file_descr -> socket_bool_option -> bool
1589 Return the current status of a boolean-valued option in the given
1591 socket.
1592 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
1597 Set or clear a boolean-valued option in the given socket.
1599 val getsockopt_int : file_descr -> socket_int_option -> int
1604 Same as Unix.getsockopt for an integer-valued socket option.
1606 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
1611 Same as Unix.setsockopt for an integer-valued socket option.
1613 val getsockopt_optint : file_descr -> socket_optint_option -> int
1618 option
1619 Same as Unix.getsockopt for a socket option whose value is an int
1621 option .
1622 val setsockopt_optint : file_descr -> socket_optint_option -> int
1627 option -> unit
1628 Same as Unix.setsockopt for a socket option whose value is an int
1630 option .
1631 val getsockopt_float : file_descr -> socket_float_option -> float
1636 Same as Unix.getsockopt for a socket option whose value is a floating-
1638 point number.
1639 val setsockopt_float : file_descr -> socket_float_option -> float ->
1644 unit
1645 Same as Unix.setsockopt for a socket option whose value is a floating-
1647 point number.
1648 === High-level network connection functions ===
1654 val open_connection : sockaddr -> Pervasives.in_channel * Perva‐
1657 sives.out_channel
1658 Connect to a server at the given address. Return a pair of buffered
1660 channels connected to the server. Remember to call Pervasives.flush on
1661 the output channel at the right times to ensure correct synchroniza‐
1662 tion.
1663 val shutdown_connection : Pervasives.in_channel -> unit
1668 ``Shut down'' a connection established with Unix.open_connection ; that
1670 is, transmit an end-of-file condition to the server reading on the
1671 other side of the connection.
1672 val establish_server : (Pervasives.in_channel -> Pervasives.out_channel
1677 -> unit) -> sockaddr -> unit
1678 Establish a server on the given address. The function given as first
1680 argument is called for each connection with two buffered channels con‐
1681 nected to the client. A new process is created for each connection. The
1682 function Unix.establish_server never returns normally.
1683 === Host and protocol databases ===
1689 type host_entry = {
1691 h_name : string ;
1692 h_aliases : string array ;
1693 h_addrtype : socket_domain ;
1694 h_addr_list : inet_addr array ;
1695 }
1696 Structure of entries in the hosts database.
1699 type protocol_entry = {
1703 p_name : string ;
1704 p_aliases : string array ;
1705 p_proto : int ;
1706 }
1707 Structure of entries in the protocols database.
1710 type service_entry = {
1714 s_name : string ;
1715 s_aliases : string array ;
1716 s_port : int ;
1717 s_proto : string ;
1718 }
1719 Structure of entries in the services database.
1722 val gethostname : unit -> string
1727 Return the name of the local host.
1729 val gethostbyname : string -> host_entry
1734 Find an entry in hosts with the given name, or raise Not_found .
1736 val gethostbyaddr : inet_addr -> host_entry
1741 Find an entry in hosts with the given address, or raise Not_found .
1743 val getprotobyname : string -> protocol_entry
1748 Find an entry in protocols with the given name, or raise Not_found .
1750 val getprotobynumber : int -> protocol_entry
1755 Find an entry in protocols with the given protocol number, or raise
1757 Not_found .
1758 val getservbyname : string -> string -> service_entry
1763 Find an entry in services with the given name, or raise Not_found .
1765 val getservbyport : int -> string -> service_entry
1770 Find an entry in services with the given service number, or raise
1772 Not_found .
1773 type addr_info = {
1777 ai_family : socket_domain ; (* Socket domain *)
1778 ai_socktype : socket_type ; (* Socket type *)
1779 ai_protocol : int ; (* Socket protocol number *)
1780 ai_addr : sockaddr ; (* Address *)
1781 ai_canonname : string ; (* Canonical host name *)
1782 }
1783 Address information returned by Unix.getaddrinfo .
1786 type getaddrinfo_option =
1790 | AI_FAMILY of socket_domain (* Impose the given socket domain *)
1791 | AI_SOCKTYPE of socket_type (* Impose the given socket type *)
1792 | AI_PROTOCOL of int (* Impose the given protocol *)
1793 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP
1794 address *)
1795 | AI_CANONNAME (* Fill the ai_canonname field of the result *)
1796 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
1797 *)
1798 Options to Unix.getaddrinfo .
1801 val getaddrinfo : string -> string -> getaddrinfo_option list ->
1806 addr_info list
1807 getaddrinfo host service opts returns a list of Unix.addr_info records
1810 describing socket parameters and addresses suitable for communicating
1811 with the given host and service. The empty list is returned if the
1812 host or service names are unknown, or the constraints expressed in opts
1813 cannot be satisfied.
1814 host is either a host name or the string representation of an IP
1817 address. host can be given as the empty string; in this case, the
1818 ``any'' address or the ``loopback'' address are used, depending whether
1819 opts contains AI_PASSIVE . service is either a service name or the
1820 string representation of a port number. service can be given as the
1821 empty string; in this case, the port field of the returned addresses is
1822 set to 0. opts is a possibly empty list of options that allows the
1823 caller to force a particular socket domain (e.g. IPv6 only or IPv4
1824 only) or a particular socket type (e.g. TCP only or UDP only).
1825 type name_info = {
1829 ni_hostname : string ; (* Name or IP address of host *)
1830 ni_service : string ;
1831 }
1832 Name of service or port number
1835 === Host and service information returned by Unix.getnameinfo. ===
1841 type getnameinfo_option =
1843 | NI_NOFQDN (* Do not qualify local host names *)
1844 | NI_NUMERICHOST (* Always return host as IP address *)
1845 | NI_NAMEREQD (* Fail if host name cannot be determined *)
1846 | NI_NUMERICSERV (* Always return service as port number *)
1847 | NI_DGRAM (* Consider the service as UDP-based instead of the
1848 default TCP *)
1849 Options to Unix.getnameinfo .
1852 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
1857 getnameinfo addr opts returns the host name and service name corre‐
1860 sponding to the socket address addr . opts is a possibly empty list of
1861 options that governs how these names are obtained. Raise Not_found if
1862 an error occurs.
1863 === Terminal interface ===
1869 === The following functions implement the POSIX standard terminal
1873 interface. They provide control over asynchronous communication ports
1874 and pseudo-terminals. Refer to the termios man page for a complete
1875 description. ===
1876 type terminal_io = {
1878 mutable c_ignbrk : bool ; (* Ignore the break condition. *)
1880 mutable c_brkint : bool ; (* Signal interrupt on break condition. *)
1882 mutable c_ignpar : bool ; (* Ignore characters with parity errors. *)
1884 mutable c_parmrk : bool ; (* Mark parity errors. *)
1886 mutable c_inpck : bool ; (* Enable parity check on input. *)
1888 mutable c_istrip : bool ; (* Strip 8th bit on input characters. *)
1890 mutable c_inlcr : bool ; (* Map NL to CR on input. *)
1892 mutable c_igncr : bool ; (* Ignore CR on input. *)
1894 mutable c_icrnl : bool ; (* Map CR to NL on input. *)
1896 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input. *)
1898 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
1900 *)
1901 mutable c_opost : bool ; (* Enable output processing. *)
1903 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
1905 tion). *)
1906 mutable c_ibaud : int ; (* Input baud rate. *)
1908 mutable c_csize : int ; (* Number of bits per character (5-8). *)
1910 mutable c_cstopb : int ; (* Number of stop bits (1-2). *)
1912 mutable c_cread : bool ; (* Reception is enabled. *)
1914 mutable c_parenb : bool ; (* Enable parity generation and detection.
1916 *)
1917 mutable c_parodd : bool ; (* Specify odd parity instead of even. *)
1919 mutable c_hupcl : bool ; (* Hang up on last close. *)
1921 mutable c_clocal : bool ; (* Ignore modem status lines. *)
1923 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP. *)
1925 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
1927 ing and editing) *)
1928 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP. *)
1930 mutable c_echo : bool ; (* Echo input characters. *)
1932 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
1934 *)
1935 mutable c_echok : bool ; (* Echo KILL (to erase the current line). *)
1937 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set. *)
1939 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C). *)
1941 mutable c_vquit : char ; (* Quit character (usually ctrl-\). *)
1943 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
1945 *)
1946 mutable c_vkill : char ; (* Kill line character (usually ctrl-U). *)
1948 mutable c_veof : char ; (* End-of-file character (usually ctrl-D). *)
1950 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
1952 *)
1953 mutable c_vmin : int ; (* Minimum number of characters to read before
1955 the read request is satisfied. *)
1956 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units). *)
1958 mutable c_vstart : char ; (* Start character (usually ctrl-Q). *)
1960 mutable c_vstop : char ; (* Stop character (usually ctrl-S). *)
1962 }
1963 val tcgetattr : file_descr -> terminal_io
1969 Return the status of the terminal referred to by the given file
1971 descriptor.
1972 type setattr_when =
1976 | TCSANOW
1977 | TCSADRAIN
1978 | TCSAFLUSH
1979 val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit
1985 Set the status of the terminal referred to by the given file descrip‐
1987 tor. The second argument indicates when the status change takes place:
1988 immediately ( TCSANOW ), when all pending output has been transmitted (
1989 TCSADRAIN ), or after flushing all input that has been received but not
1990 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
1991 parameters; TCSAFLUSH , when changing the input parameters.
1992 val tcsendbreak : file_descr -> int -> unit
1997 Send a break condition on the given file descriptor. The second argu‐
1999 ment is the duration of the break, in 0.1s units; 0 means standard
2000 duration (0.25s).
2001 val tcdrain : file_descr -> unit
2006 Waits until all output written on the given file descriptor has been
2008 transmitted.
2009 type flush_queue =
2013 | TCIFLUSH
2014 | TCOFLUSH
2015 | TCIOFLUSH
2016 val tcflush : file_descr -> flush_queue -> unit
2022 Discard data written on the given file descriptor but not yet transmit‐
2024 ted, or data received but not yet read, depending on the second argu‐
2025 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2026 data written but not transmitted, and TCIOFLUSH flushes both.
2027 type flow_action =
2031 | TCOOFF
2032 | TCOON
2033 | TCIOFF
2034 | TCION
2035 val tcflow : file_descr -> flow_action -> unit
2041 Suspend or restart reception or transmission of data on the given file
2043 descriptor, depending on the second argument: TCOOFF suspends output,
2044 TCOON restarts output, TCIOFF transmits a STOP character to suspend
2045 input, and TCION transmits a START character to restart input.
2046 val setsid : unit -> int
2051 Put the calling process in a new session and detach it from its con‐
2053 trolling terminal.
2054OCamldoc 2007-05-24 Unix(3)