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 =
29 | E2BIG (* Argument list too long *)
30 | EACCES (* Permission denied *)
31 | EAGAIN (* Resource temporarily unavailable; try again *)
32 | EBADF (* Bad file descriptor *)
33 | EBUSY (* Resource unavailable *)
34 | ECHILD (* No child process *)
35 | EDEADLK (* Resource deadlock would occur *)
36 | EDOM (* Domain error for math functions, etc. *)
37 | EEXIST (* File exists *)
38 | EFAULT (* Bad address *)
39 | EFBIG (* File too large *)
40 | EINTR (* Function interrupted by signal *)
41 | EINVAL (* Invalid argument *)
42 | EIO (* Hardware I/O error *)
43 | EISDIR (* Is a directory *)
44 | EMFILE (* Too many open files by the process *)
45 | EMLINK (* Too many links *)
46 | ENAMETOOLONG (* Filename too long *)
47 | ENFILE (* Too many open files in the system *)
48 | ENODEV (* No such device *)
49 | ENOENT (* No such file or directory *)
50 | ENOEXEC (* Not an executable file *)
51 | ENOLCK (* No locks available *)
52 | ENOMEM (* Not enough memory *)
53 | ENOSPC (* No space left on device *)
54 | ENOSYS (* Function not supported *)
55 | ENOTDIR (* Not a directory *)
56 | ENOTEMPTY (* Directory not empty *)
57 | ENOTTY (* Inappropriate I/O control operation *)
58 | ENXIO (* No such device or address *)
59 | EPERM (* Operation not permitted *)
60 | EPIPE (* Broken pipe *)
61 | ERANGE (* Result too large *)
62 | EROFS (* Read-only file system *)
63 | ESPIPE (* Invalid seek e.g. on a pipe *)
64 | ESRCH (* No such process *)
65 | EXDEV (* Invalid link *)
66 | EWOULDBLOCK (* Operation would block *)
67 | EINPROGRESS (* Operation now in progress *)
68 | EALREADY (* Operation already in progress *)
69 | ENOTSOCK (* Socket operation on non-socket *)
70 | EDESTADDRREQ (* Destination address required *)
71 | EMSGSIZE (* Message too long *)
72 | EPROTOTYPE (* Protocol wrong type for socket *)
73 | ENOPROTOOPT (* Protocol not available *)
74 | EPROTONOSUPPORT (* Protocol not supported *)
75 | ESOCKTNOSUPPORT (* Socket type not supported *)
76 | EOPNOTSUPP (* Operation not supported on socket *)
77 | EPFNOSUPPORT (* Protocol family not supported *)
78 | EAFNOSUPPORT (* Address family not supported by protocol family *)
79 | EADDRINUSE (* Address already in use *)
80 | EADDRNOTAVAIL (* Can't assign requested address *)
81 | ENETDOWN (* Network is down *)
82 | ENETUNREACH (* Network is unreachable *)
83 | ENETRESET (* Network dropped connection on reset *)
84 | ECONNABORTED (* Software caused connection abort *)
85 | ECONNRESET (* Connection reset by peer *)
86 | ENOBUFS (* No buffer space available *)
87 | EISCONN (* Socket is already connected *)
88 | ENOTCONN (* Socket is not connected *)
89 | ESHUTDOWN (* Can't send after socket shutdown *)
90 | ETOOMANYREFS (* Too many references: can't splice *)
91 | ETIMEDOUT (* Connection timed out *)
92 | ECONNREFUSED (* Connection refused *)
93 | EHOSTDOWN (* Host is down *)
94 | EHOSTUNREACH (* No route to host *)
95 | ELOOP (* Too many levels of symbolic links *)
96 | EOVERFLOW (* File size or position not representable *)
97 | EUNKNOWNERR of int (* Unknown error *)
98 The type of error codes. Errors defined in the POSIX standard and
101 additional errors from UNIX98 and BSD. All other errors are mapped to
102 EUNKNOWNERR.
103 exception Unix_error of error * string * string
108 Raised by the system calls below when an error is encountered. The
111 first component is the error code; the second component is the function
112 name; the third component is the string parameter to the function, if
113 it has one, or the empty string otherwise.
114 val error_message : error -> string
119 Return a string describing the given error code.
121 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
126 handle_unix_error f x applies f to x and returns the result. If the
129 exception Unix_error is raised, it prints a message describing the
130 error and exits with code 2.
131 === Access to the process environment ===
137 val environment : unit -> string array
140 Return the process environment, as an array of strings with the format
142 ``variable=value''.
143 val getenv : string -> string
148 Return the value associated to a variable in the process environment.
150 Raise Not_found if the variable is unbound. (This function is identi‐
151 cal to Sys.getenv .)
152 val putenv : string -> string -> unit
157 Unix.putenv name value sets the value associated to a variable in the
160 process environment. name is the name of the environment variable, and
161 value its new associated value.
162 === Process handling ===
168 type process_status =
171 | WEXITED of int (* The process terminated normally by exit ; the
172 argument is the return code. *)
173 | WSIGNALED of int (* The process was killed by a signal; the argu‐
174 ment is the signal number. *)
175 | WSTOPPED of int (* The process was stopped by a signal; the argu‐
176 ment is the signal number. *)
177 The termination status of a process. See module Sys for the defini‐
180 tions of the standard signal numbers. Note that they are not the num‐
181 bers used by the OS.
182 type wait_flag =
186 | WNOHANG (* do not block if no child has died yet, but immediately
187 return with a pid equal to 0. *)
188 | WUNTRACED (* report also the children that receive stop signals. *)
189 Flags for Unix.waitpid .
192 val execv : string -> string array -> 'a
197 execv prog args execute the program in file prog , with the arguments
200 args , and the current process environment. These execv* functions
201 never return: on success, the current program is replaced by the new
202 one; on failure, a Unix.Unix_error exception is raised.
203 val execve : string -> string array -> string array -> 'a
208 Same as Unix.execv , except that the third argument provides the envi‐
210 ronment to the program executed.
211 val execvp : string -> string array -> 'a
216 Same as Unix.execv , except that the program is searched in the path.
218 val execvpe : string -> string array -> string array -> 'a
223 Same as Unix.execve , except that the program is searched in the path.
225 val fork : unit -> int
230 Fork a new process. The returned integer is 0 for the child process,
232 the pid of the child process for the parent process.
233 val wait : unit -> int * process_status
238 Wait until one of the children processes die, and return its pid and
240 termination status.
241 val waitpid : wait_flag list -> int -> int * process_status
246 Same as Unix.wait , but waits for the child process whose pid is given.
248 A pid of -1 means wait for any child. A pid of 0 means wait for any
249 child in the same process group as the current process. Negative pid
250 arguments represent process groups. The list of options indicates
251 whether waitpid should return immediately without waiting, or also
252 report stopped children.
253 val system : string -> process_status
258 Execute the given command, wait until it terminates, and return its
260 termination status. The string is interpreted by the shell /bin/sh and
261 therefore can contain redirections, quotes, variables, etc. The result
262 WEXITED 127 indicates that the shell couldn't be executed.
263 val getpid : unit -> int
268 Return the pid of the process.
270 val getppid : unit -> int
275 Return the pid of the parent process.
277 val nice : int -> int
282 Change the process priority. The integer argument is added to the
284 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
285 ties.) Return the new nice value.
286 === Basic file input/output ===
292 type file_descr
295 The abstract type of file descriptors.
298 val stdin : file_descr
303 File descriptor for standard input.
305 val stdout : file_descr
310 File descriptor for standard output.
312 val stderr : file_descr
317 File descriptor for standard error.
319 type open_flag =
323 | O_RDONLY (* Open for reading *)
324 | O_WRONLY (* Open for writing *)
325 | O_RDWR (* Open for reading and writing *)
326 | O_NONBLOCK (* Open in non-blocking mode *)
327 | O_APPEND (* Open for append *)
328 | O_CREAT (* Create if nonexistent *)
329 | O_TRUNC (* Truncate to 0 length if existing *)
330 | O_EXCL (* Fail if existing *)
331 | O_NOCTTY (* Don't make this dev a controlling tty *)
332 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
333 pletion' *)
334 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
335 pletion' *)
336 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
337 *)
338 The flags to Unix.openfile .
341 type file_perm = int
345 The type of file access rights, e.g. 0o640 is read and write for user,
348 read for group, none for others
349 val openfile : string -> open_flag list -> file_perm -> file_descr
354 Open the named file with the given flags. Third argument is the permis‐
356 sions to give to the file if it is created. Return a file descriptor on
357 the named file.
358 val close : file_descr -> unit
363 Close a file descriptor.
365 val read : file_descr -> string -> int -> int -> int
370 read fd buff ofs len reads len characters from descriptor fd , storing
373 them in string buff , starting at position ofs in string buff . Return
374 the number of characters actually read.
375 val write : file_descr -> string -> int -> int -> int
380 write fd buff ofs len writes len characters to descriptor fd , taking
383 them from string buff , starting at position ofs in string buff .
384 Return the number of characters actually written. write repeats the
385 writing operation until all characters have been written or an error
386 occurs.
387 val single_write : file_descr -> string -> int -> int -> int
392 Same as write , but attempts to write only once. Thus, if an error
394 occurs, single_write guarantees that no data has been written.
395 === Interfacing with the standard input/output library ===
401 val in_channel_of_descr : file_descr -> Pervasives.in_channel
404 Create an input channel reading from the given descriptor. The channel
406 is initially in binary mode; use set_binary_mode_in ic false if text
407 mode is desired.
408 val out_channel_of_descr : file_descr -> Pervasives.out_channel
413 Create an output channel writing on the given descriptor. The channel
415 is initially in binary mode; use set_binary_mode_out oc false if text
416 mode is desired.
417 val descr_of_in_channel : Pervasives.in_channel -> file_descr
422 Return the descriptor corresponding to an input channel.
424 val descr_of_out_channel : Pervasives.out_channel -> file_descr
429 Return the descriptor corresponding to an output channel.
431 === Seeking and truncating ===
437 type seek_command =
440 | SEEK_SET (* indicates positions relative to the beginning of the
441 file *)
442 | SEEK_CUR (* indicates positions relative to the current position *)
443 | SEEK_END (* indicates positions relative to the end of the file *)
444 Positioning modes for Unix.lseek .
447 val lseek : file_descr -> int -> seek_command -> int
452 Set the current position for a file descriptor
454 val truncate : string -> int -> unit
459 Truncates the named file to the given size.
461 val ftruncate : file_descr -> int -> unit
466 Truncates the file corresponding to the given descriptor to the given
468 size.
469 === File status ===
475 type file_kind =
478 | S_REG (* Regular file *)
479 | S_DIR (* Directory *)
480 | S_CHR (* Character device *)
481 | S_BLK (* Block device *)
482 | S_LNK (* Symbolic link *)
483 | S_FIFO (* Named pipe *)
484 | S_SOCK (* Socket *)
485 type stats = {
490 st_dev : int ; (* Device number *)
491 st_ino : int ; (* Inode number *)
492 st_kind : file_kind ; (* Kind of the file *)
493 st_perm : file_perm ; (* Access rights *)
494 st_nlink : int ; (* Number of links *)
495 st_uid : int ; (* User id of the owner *)
496 st_gid : int ; (* Group ID of the file's group *)
497 st_rdev : int ; (* Device minor number *)
498 st_size : int ; (* Size in bytes *)
499 st_atime : float ; (* Last access time *)
500 st_mtime : float ; (* Last modification time *)
501 st_ctime : float ; (* Last status change time *)
502 }
503 The informations returned by the Unix.stat calls.
506 val stat : string -> stats
511 Return the information for the named file.
513 val lstat : string -> stats
518 Same as Unix.stat , but in case the file is a symbolic link, return the
520 information for the link itself.
521 val fstat : file_descr -> stats
526 Return the information for the file associated with the given descrip‐
528 tor.
529 val isatty : file_descr -> bool
534 Return true if the given file descriptor refers to a terminal or con‐
536 sole window, false otherwise.
537 === File operations on large files ===
543 module LargeFile : sig end
546 File operations on large files. This sub-module provides 64-bit vari‐
549 ants of the functions Unix.lseek (for positioning a file descriptor),
550 Unix.truncate and Unix.ftruncate (for changing the size of a file), and
551 Unix.stat , Unix.lstat and Unix.fstat (for obtaining information on
552 files). These alternate functions represent positions and sizes by
553 64-bit integers (type int64 ) instead of regular integers (type int ),
554 thus allowing operating on files whose sizes are greater than max_int .
555 === Operations on file names ===
561 val unlink : string -> unit
564 Removes the named file
566 val rename : string -> string -> unit
571 rename old new changes the name of a file from old to new .
574 val link : string -> string -> unit
579 link source dest creates a hard link named dest to the file named
582 source .
583 === File permissions and ownership ===
589 type access_permission =
592 | R_OK (* Read permission *)
593 | W_OK (* Write permission *)
594 | X_OK (* Execution permission *)
595 | F_OK (* File exists *)
596 Flags for the Unix.access call.
599 val chmod : string -> file_perm -> unit
604 Change the permissions of the named file.
606 val fchmod : file_descr -> file_perm -> unit
611 Change the permissions of an opened file.
613 val chown : string -> int -> int -> unit
618 Change the owner uid and owner gid of the named file.
620 val fchown : file_descr -> int -> int -> unit
625 Change the owner uid and owner gid of an opened file.
627 val umask : int -> int
632 Set the process's file mode creation mask, and return the previous
634 mask.
635 val access : string -> access_permission list -> unit
640 Check that the process has the given permissions over the named file.
642 Raise Unix_error otherwise.
643 === Operations on file descriptors ===
649 val dup : file_descr -> file_descr
652 Return a new file descriptor referencing the same file as the given
654 descriptor.
655 val dup2 : file_descr -> file_descr -> unit
660 dup2 fd1 fd2 duplicates fd1 to fd2 , closing fd2 if already opened.
663 val set_nonblock : file_descr -> unit
668 Set the ``non-blocking'' flag on the given descriptor. When the
670 non-blocking flag is set, reading on a descriptor on which there is
671 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
672 instead of blocking; writing on a descriptor on which there is tempo‐
673 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
674 val clear_nonblock : file_descr -> unit
679 Clear the ``non-blocking'' flag on the given descriptor. See
681 Unix.set_nonblock .
682 val set_close_on_exec : file_descr -> unit
687 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
689 with the close-on-exec flag is automatically closed when the current
690 process starts another program with one of the exec functions.
691 val clear_close_on_exec : file_descr -> unit
696 Clear the ``close-on-exec'' flag on the given descriptor. See
698 Unix.set_close_on_exec .
699 === Directories ===
705 val mkdir : string -> file_perm -> unit
708 Create a directory with the given permissions.
710 val rmdir : string -> unit
715 Remove an empty directory.
717 val chdir : string -> unit
722 Change the process working directory.
724 val getcwd : unit -> string
729 Return the name of the current working directory.
731 val chroot : string -> unit
736 Change the process root directory.
738 type dir_handle
742 The type of descriptors over opened directories.
745 val opendir : string -> dir_handle
750 Open a descriptor on a directory
752 val readdir : dir_handle -> string
757 Return the next entry in a directory.
759 Raises End_of_file when the end of the directory has been reached.
761 val rewinddir : dir_handle -> unit
766 Reposition the descriptor to the beginning of the directory
768 val closedir : dir_handle -> unit
773 Close a directory descriptor.
775 === Pipes and redirections ===
781 val pipe : unit -> file_descr * file_descr
784 Create a pipe. The first component of the result is opened for reading,
786 that's the exit to the pipe. The second component is opened for writ‐
787 ing, that's the entrance to the pipe.
788 val mkfifo : string -> file_perm -> unit
793 Create a named pipe with the given permissions.
795 === High-level process and redirection management ===
801 val create_process : string -> string array -> file_descr -> file_descr
804 -> file_descr -> int
805 create_process prog args new_stdin new_stdout new_stderr forks a new
808 process that executes the program in file prog , with arguments args .
809 The pid of the new process is returned immediately; the new process
810 executes concurrently with the current process. The standard input and
811 outputs of the new process are connected to the descriptors new_stdin ,
812 new_stdout and new_stderr . Passing e.g. stdout for new_stdout pre‐
813 vents the redirection and causes the new process to have the same stan‐
814 dard output as the current process. The executable file prog is
815 searched in the path. The new process has the same environment as the
816 current process.
817 val create_process_env : string -> string array -> string array ->
822 file_descr -> file_descr -> file_descr -> int
823 create_process_env prog args env new_stdin new_stdout new_stderr works
826 as Unix.create_process , except that the extra argument env specifies
827 the environment passed to the program.
828 val open_process_in : string -> Pervasives.in_channel
833 High-level pipe and process management. This function runs the given
835 command in parallel with the program. The standard output of the com‐
836 mand is redirected to a pipe, which can be read via the returned input
837 channel. The command is interpreted by the shell /bin/sh (cf. system
838 ).
839 val open_process_out : string -> Pervasives.out_channel
844 Same as Unix.open_process_in , but redirect the standard input of the
846 command to a pipe. Data written to the returned output channel is sent
847 to the standard input of the command. Warning: writes on output chan‐
848 nels are buffered, hence be careful to call Pervasives.flush at the
849 right times to ensure correct synchronization.
850 val open_process : string -> Pervasives.in_channel * Perva‐
855 sives.out_channel
856 Same as Unix.open_process_out , but redirects both the standard input
858 and standard output of the command to pipes connected to the two
859 returned channels. The input channel is connected to the output of the
860 command, and the output channel to the input of the command.
861 val open_process_full : string -> string array -> Pervasives.in_channel
866 * Pervasives.out_channel * Pervasives.in_channel
867 Similar to Unix.open_process , but the second argument specifies the
869 environment passed to the command. The result is a triple of channels
870 connected respectively to the standard output, standard input, and
871 standard error of the command.
872 val close_process_in : Pervasives.in_channel -> process_status
877 Close channels opened by Unix.open_process_in , wait for the associated
879 command to terminate, and return its termination status.
880 val close_process_out : Pervasives.out_channel -> process_status
885 Close channels opened by Unix.open_process_out , wait for the associ‐
887 ated command to terminate, and return its termination status.
888 val close_process : Pervasives.in_channel * Pervasives.out_channel ->
893 process_status
894 Close channels opened by Unix.open_process , wait for the associated
896 command to terminate, and return its termination status.
897 val close_process_full : Pervasives.in_channel * Pervasives.out_channel
902 * Pervasives.in_channel -> process_status
903 Close channels opened by Unix.open_process_full , wait for the associ‐
905 ated command to terminate, and return its termination status.
906 === Symbolic links ===
912 val symlink : string -> string -> unit
915 symlink source dest creates the file dest as a symbolic link to the
918 file source .
919 val readlink : string -> string
924 Read the contents of a link.
926 === Polling ===
932 val select : file_descr list -> file_descr list -> file_descr list ->
935 float -> file_descr list * file_descr list * file_descr list
936 Wait until some input/output operations become possible on some chan‐
938 nels. The three list arguments are, respectively, a set of descriptors
939 to check for reading (first argument), for writing (second argument),
940 or for exceptional conditions (third argument). The fourth argument is
941 the maximal timeout, in seconds; a negative fourth argument means no
942 timeout (unbounded wait). The result is composed of three sets of
943 descriptors: those ready for reading (first component), ready for writ‐
944 ing (second component), and over which an exceptional condition is
945 pending (third component).
946 === Locking ===
952 type lock_command =
955 | F_ULOCK (* Unlock a region *)
956 | F_LOCK (* Lock a region for writing, and block if already locked *)
957 | F_TLOCK (* Lock a region for writing, or fail if already locked *)
958 | F_TEST (* Test a region for other process locks *)
959 | F_RLOCK (* Lock a region for reading, and block if already locked
960 *)
961 | F_TRLOCK (* Lock a region for reading, or fail if already locked *)
962 Commands for Unix.lockf .
965 val lockf : file_descr -> lock_command -> int -> unit
970 lockf fd cmd size puts a lock on a region of the file opened as fd .
973 The region starts at the current read/write position for fd (as set by
974 Unix.lseek ), and extends size bytes forward if size is positive, size
975 bytes backwards if size is negative, or to the end of the file if size
976 is zero. A write lock prevents any other process from acquiring a read
977 or write lock on the region. A read lock prevents any other process
978 from acquiring a write lock on the region, but lets other processes
979 acquire read locks on it.
980 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
982 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
983 read lock on the specified region. If one or several locks put by
984 another process prevent the current process from acquiring the lock,
985 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
986 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
987 whatever locks the current process has on the specified region.
988 Finally, the F_TEST command tests whether a write lock can be acquired
989 on the specified region, without actually putting a lock. It returns
990 immediately if successful, or fails otherwise.
991 === Signals Note: installation of signal handlers is performed via the
997 functions Sys.signal and Sys.set_signal. ===
998 val kill : int -> int -> unit
1001 kill pid sig sends signal number sig to the process with id pid .
1004 type sigprocmask_command =
1008 | SIG_SETMASK
1009 | SIG_BLOCK
1010 | SIG_UNBLOCK
1011 val sigprocmask : sigprocmask_command -> int list -> int list
1017 sigprocmask cmd sigs changes the set of blocked signals. If cmd is
1020 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1021 cmd is SIG_BLOCK , the signals in sigs are added to the set of blocked
1022 signals. If cmd is SIG_UNBLOCK , the signals in sigs are removed from
1023 the set of blocked signals. sigprocmask returns the set of previously
1024 blocked signals.
1025 val sigpending : unit -> int list
1030 Return the set of blocked signals that are currently pending.
1032 val sigsuspend : int list -> unit
1037 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1040 for a non-ignored, non-blocked signal to be delivered. On return, the
1041 blocked signals are reset to their initial value.
1042 val pause : unit -> unit
1047 Wait until a non-ignored, non-blocked signal is delivered.
1049 === Time functions ===
1055 type process_times = {
1058 tms_utime : float ; (* User time for the process *)
1059 tms_stime : float ; (* System time for the process *)
1060 tms_cutime : float ; (* User time for the children processes *)
1061 tms_cstime : float ; (* System time for the children processes *)
1062 }
1063 The execution times (CPU times) of a process.
1066 type tm = {
1070 tm_sec : int ; (* Seconds 0..60 *)
1071 tm_min : int ; (* Minutes 0..59 *)
1072 tm_hour : int ; (* Hours 0..23 *)
1073 tm_mday : int ; (* Day of month 1..31 *)
1074 tm_mon : int ; (* Month of year 0..11 *)
1075 tm_year : int ; (* Year - 1900 *)
1076 tm_wday : int ; (* Day of week (Sunday is 0) *)
1077 tm_yday : int ; (* Day of year 0..365 *)
1078 tm_isdst : bool ; (* Daylight time savings in effect *)
1079 }
1080 The type representing wallclock time and calendar date.
1083 val time : unit -> float
1088 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1090 val gettimeofday : unit -> float
1095 Same as Unix.time , but with resolution better than 1 second.
1097 val gmtime : float -> tm
1102 Convert a time in seconds, as returned by Unix.time , into a date and a
1104 time. Assumes UTC (Coordinated Universal Time), also known as GMT.
1105 val localtime : float -> tm
1110 Convert a time in seconds, as returned by Unix.time , into a date and a
1112 time. Assumes the local time zone.
1113 val mktime : tm -> float * tm
1118 Convert a date and time, specified by the tm argument, into a time in
1120 seconds, as returned by Unix.time . The tm_isdst , tm_wday and tm_yday
1121 fields of tm are ignored. Also return a normalized copy of the given
1122 tm record, with the tm_wday , tm_yday , and tm_isdst fields recomputed
1123 from the other fields, and the other fields normalized (so that, e.g.,
1124 40 October is changed into 9 November). The tm argument is interpreted
1125 in the local time zone.
1126 val alarm : int -> int
1131 Schedule a SIGALRM signal after the given number of seconds.
1133 val sleep : int -> unit
1138 Stop execution for the given number of seconds.
1140 val times : unit -> process_times
1145 Return the execution times of the process.
1147 val utimes : string -> float -> float -> unit
1152 Set the last access time (second arg) and last modification time (third
1154 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1155 1, 1970. A time of 0.0 is interpreted as the current time.
1156 type interval_timer =
1160 | ITIMER_REAL (* decrements in real time, and sends the signal
1161 SIGALRM when expired. *)
1162 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1163 SIGVTALRM when expired. *)
1164 | ITIMER_PROF (* (for profiling) decrements both when the process is
1165 running and when the system is running on behalf of the process; it
1166 sends SIGPROF when expired. *)
1167 The three kinds of interval timers.
1170 type interval_timer_status = {
1174 it_interval : float ; (* Period *)
1175 it_value : float ; (* Current value of the timer *)
1176 }
1177 The type describing the status of an interval timer
1180 val getitimer : interval_timer -> interval_timer_status
1185 Return the current status of the given interval timer.
1187 val setitimer : interval_timer -> interval_timer_status -> inter‐
1192 val_timer_status
1193 setitimer t s sets the interval timer t and returns its previous sta‐
1196 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1197 is the time to the next timer expiration; s.it_interval , if nonzero,
1198 specifies a value to be used in reloading it_value when the timer
1199 expires. Setting s.it_value to zero disable the timer. Setting
1200 s.it_interval to zero causes the timer to be disabled after its next
1201 expiration.
1202 === User id, group id ===
1208 val getuid : unit -> int
1211 Return the user id of the user executing the process.
1213 val geteuid : unit -> int
1218 Return the effective user id under which the process runs.
1220 val setuid : int -> unit
1225 Set the real user id and effective user id for the process.
1227 val getgid : unit -> int
1232 Return the group id of the user executing the process.
1234 val getegid : unit -> int
1239 Return the effective group id under which the process runs.
1241 val setgid : int -> unit
1246 Set the real group id and effective group id for the process.
1248 val getgroups : unit -> int array
1253 Return the list of groups to which the user executing the process
1255 belongs.
1256 type passwd_entry = {
1260 pw_name : string ;
1261 pw_passwd : string ;
1262 pw_uid : int ;
1263 pw_gid : int ;
1264 pw_gecos : string ;
1265 pw_dir : string ;
1266 pw_shell : string ;
1267 }
1268 Structure of entries in the passwd database.
1271 type group_entry = {
1275 gr_name : string ;
1276 gr_passwd : string ;
1277 gr_gid : int ;
1278 gr_mem : string array ;
1279 }
1280 Structure of entries in the groups database.
1283 val getlogin : unit -> string
1288 Return the login name of the user executing the process.
1290 val getpwnam : string -> passwd_entry
1295 Find an entry in passwd with the given name, or raise Not_found .
1297 val getgrnam : string -> group_entry
1302 Find an entry in group with the given name, or raise Not_found .
1304 val getpwuid : int -> passwd_entry
1309 Find an entry in passwd with the given user id, or raise Not_found .
1311 val getgrgid : int -> group_entry
1316 Find an entry in group with the given group id, or raise Not_found .
1318 === Internet addresses ===
1324 type inet_addr
1327 The abstract type of Internet addresses.
1330 val inet_addr_of_string : string -> inet_addr
1335 Conversion from the printable representation of an Internet address to
1337 its internal representation. The argument string consists of 4 numbers
1338 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1339 8 numbers separated by colons for IPv6 addresses. Raise Failure when
1340 given a string that does not match these formats.
1341 val string_of_inet_addr : inet_addr -> string
1346 Return the printable representation of the given Internet address. See
1348 Unix.inet_addr_of_string for a description of the printable representa‐
1349 tion.
1350 val inet_addr_any : inet_addr
1355 A special IPv4 address, for use only with bind , representing all the
1357 Internet addresses that the host machine possesses.
1358 val inet_addr_loopback : inet_addr
1363 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1365 val inet6_addr_any : inet_addr
1370 A special IPv6 address, for use only with bind , representing all the
1372 Internet addresses that the host machine possesses.
1373 val inet6_addr_loopback : inet_addr
1378 A special IPv6 address representing the host machine ( ::1 ).
1380 === Sockets ===
1386 type socket_domain =
1389 | PF_UNIX (* Unix domain *)
1390 | PF_INET (* Internet domain (IPv4) *)
1391 | PF_INET6 (* Internet domain (IPv6) *)
1392 The type of socket domains. Not all platforms support IPv6 sockets
1395 (type PF_INET6 ).
1396 type socket_type =
1400 | SOCK_STREAM (* Stream socket *)
1401 | SOCK_DGRAM (* Datagram socket *)
1402 | SOCK_RAW (* Raw socket *)
1403 | SOCK_SEQPACKET (* Sequenced packets socket *)
1404 The type of socket kinds, specifying the semantics of communications.
1407 type sockaddr =
1411 | ADDR_UNIX of string
1412 | ADDR_INET of inet_addr * int (* The type of socket addresses.
1413 ADDR_UNIX name is a socket address in the Unix domain; name is a file
1414 name in the file system. ADDR_INET(addr,port) is a socket address in
1415 the Internet domain; addr is the Internet address of the machine, and
1416 port is the port number. *)
1417 val socket : socket_domain -> socket_type -> int -> file_descr
1423 Create a new socket in the given domain, and with the given kind. The
1425 third argument is the protocol type; 0 selects the default protocol for
1426 that kind of sockets.
1427 val domain_of_sockaddr : sockaddr -> socket_domain
1432 Return the socket domain adequate for the given socket address.
1434 val socketpair : socket_domain -> socket_type -> int -> file_descr *
1439 file_descr
1440 Create a pair of unnamed sockets, connected together.
1442 val accept : file_descr -> file_descr * sockaddr
1447 Accept connections on the given socket. The returned descriptor is a
1449 socket connected to the client; the returned address is the address of
1450 the connecting client.
1451 val bind : file_descr -> sockaddr -> unit
1456 Bind a socket to an address.
1458 val connect : file_descr -> sockaddr -> unit
1463 Connect a socket to an address.
1465 val listen : file_descr -> int -> unit
1470 Set up a socket for receiving connection requests. The integer argument
1472 is the maximal number of pending requests.
1473 type shutdown_command =
1477 | SHUTDOWN_RECEIVE (* Close for receiving *)
1478 | SHUTDOWN_SEND (* Close for sending *)
1479 | SHUTDOWN_ALL (* Close both *)
1480 The type of commands for shutdown .
1483 val shutdown : file_descr -> shutdown_command -> unit
1488 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
1490 reads on the other end of the connection to return an end-of-file con‐
1491 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
1492 tion to return a closed pipe condition ( SIGPIPE signal).
1493 val getsockname : file_descr -> sockaddr
1498 Return the address of the given socket.
1500 val getpeername : file_descr -> sockaddr
1505 Return the address of the host connected to the given socket.
1507 type msg_flag =
1511 | MSG_OOB
1512 | MSG_DONTROUTE
1513 | MSG_PEEK (* The flags for Unix.recv , Unix.recvfrom , Unix.send and
1514 Unix.sendto . *)
1515 val recv : file_descr -> string -> int -> int -> msg_flag list -> int
1521 Receive data from a connected socket.
1523 val recvfrom : file_descr -> string -> int -> int -> msg_flag list ->
1528 int * sockaddr
1529 Receive data from an unconnected socket.
1531 val send : file_descr -> string -> int -> int -> msg_flag list -> int
1536 Send data over a connected socket.
1538 val sendto : file_descr -> string -> int -> int -> msg_flag list ->
1543 sockaddr -> int
1544 Send data over an unconnected socket.
1546 === Socket options ===
1552 type socket_bool_option =
1555 | SO_DEBUG (* Record debugging information *)
1556 | SO_BROADCAST (* Permit sending of broadcast messages *)
1557 | SO_REUSEADDR (* Allow reuse of local addresses for bind *)
1558 | SO_KEEPALIVE (* Keep connection active *)
1559 | SO_DONTROUTE (* Bypass the standard routing algorithms *)
1560 | SO_OOBINLINE (* Leave out-of-band data in line *)
1561 | SO_ACCEPTCONN (* Report whether socket listening is enabled *)
1562 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets *)
1563 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address *)
1564 The socket options that can be consulted with Unix.getsockopt and modi‐
1567 fied with Unix.setsockopt . These options have a boolean ( true /
1568 false ) value.
1569 type socket_int_option =
1573 | SO_SNDBUF (* Size of send buffer *)
1574 | SO_RCVBUF (* Size of received buffer *)
1575 | SO_ERROR (* Deprecated. Use Unix.getsockopt_error instead. *)
1576 | SO_TYPE (* Report the socket type *)
1577 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
1578 tions *)
1579 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
1580 tions *)
1581 The socket options that can be consulted with Unix.getsockopt_int and
1584 modified with Unix.setsockopt_int . These options have an integer
1585 value.
1586 type socket_optint_option =
1590 | SO_LINGER (* Whether to linger on closed connections that have data
1591 present, and for how long (in seconds) *)
1592 The socket options that can be consulted with Unix.getsockopt_optint
1595 and modified with Unix.setsockopt_optint . These options have a value
1596 of type int option , with None meaning ``disabled''.
1597 type socket_float_option =
1601 | SO_RCVTIMEO (* Timeout for input operations *)
1602 | SO_SNDTIMEO (* Timeout for output operations *)
1603 The socket options that can be consulted with Unix.getsockopt_float and
1606 modified with Unix.setsockopt_float . These options have a float‐
1607 ing-point value representing a time in seconds. The value 0 means
1608 infinite timeout.
1609 val getsockopt : file_descr -> socket_bool_option -> bool
1614 Return the current status of a boolean-valued option in the given
1616 socket.
1617 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
1622 Set or clear a boolean-valued option in the given socket.
1624 val getsockopt_int : file_descr -> socket_int_option -> int
1629 Same as Unix.getsockopt for an integer-valued socket option.
1631 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
1636 Same as Unix.setsockopt for an integer-valued socket option.
1638 val getsockopt_optint : file_descr -> socket_optint_option -> int
1643 option
1644 Same as Unix.getsockopt for a socket option whose value is an int
1646 option .
1647 val setsockopt_optint : file_descr -> socket_optint_option -> int
1652 option -> unit
1653 Same as Unix.setsockopt for a socket option whose value is an int
1655 option .
1656 val getsockopt_float : file_descr -> socket_float_option -> float
1661 Same as Unix.getsockopt for a socket option whose value is a float‐
1663 ing-point number.
1664 val setsockopt_float : file_descr -> socket_float_option -> float ->
1669 unit
1670 Same as Unix.setsockopt for a socket option whose value is a float‐
1672 ing-point number.
1673 val getsockopt_error : file_descr -> error option
1678 Return the error condition associated with the given socket, and clear
1680 it.
1681 === High-level network connection functions ===
1687 val open_connection : sockaddr -> Pervasives.in_channel * Perva‐
1690 sives.out_channel
1691 Connect to a server at the given address. Return a pair of buffered
1693 channels connected to the server. Remember to call Pervasives.flush on
1694 the output channel at the right times to ensure correct synchroniza‐
1695 tion.
1696 val shutdown_connection : Pervasives.in_channel -> unit
1701 ``Shut down'' a connection established with Unix.open_connection ; that
1703 is, transmit an end-of-file condition to the server reading on the
1704 other side of the connection.
1705 val establish_server : (Pervasives.in_channel -> Pervasives.out_channel
1710 -> unit) -> sockaddr -> unit
1711 Establish a server on the given address. The function given as first
1713 argument is called for each connection with two buffered channels con‐
1714 nected to the client. A new process is created for each connection. The
1715 function Unix.establish_server never returns normally.
1716 === Host and protocol databases ===
1722 type host_entry = {
1725 h_name : string ;
1726 h_aliases : string array ;
1727 h_addrtype : socket_domain ;
1728 h_addr_list : inet_addr array ;
1729 }
1730 Structure of entries in the hosts database.
1733 type protocol_entry = {
1737 p_name : string ;
1738 p_aliases : string array ;
1739 p_proto : int ;
1740 }
1741 Structure of entries in the protocols database.
1744 type service_entry = {
1748 s_name : string ;
1749 s_aliases : string array ;
1750 s_port : int ;
1751 s_proto : string ;
1752 }
1753 Structure of entries in the services database.
1756 val gethostname : unit -> string
1761 Return the name of the local host.
1763 val gethostbyname : string -> host_entry
1768 Find an entry in hosts with the given name, or raise Not_found .
1770 val gethostbyaddr : inet_addr -> host_entry
1775 Find an entry in hosts with the given address, or raise Not_found .
1777 val getprotobyname : string -> protocol_entry
1782 Find an entry in protocols with the given name, or raise Not_found .
1784 val getprotobynumber : int -> protocol_entry
1789 Find an entry in protocols with the given protocol number, or raise
1791 Not_found .
1792 val getservbyname : string -> string -> service_entry
1797 Find an entry in services with the given name, or raise Not_found .
1799 val getservbyport : int -> string -> service_entry
1804 Find an entry in services with the given service number, or raise
1806 Not_found .
1807 type addr_info = {
1811 ai_family : socket_domain ; (* Socket domain *)
1812 ai_socktype : socket_type ; (* Socket type *)
1813 ai_protocol : int ; (* Socket protocol number *)
1814 ai_addr : sockaddr ; (* Address *)
1815 ai_canonname : string ; (* Canonical host name *)
1816 }
1817 Address information returned by Unix.getaddrinfo .
1820 type getaddrinfo_option =
1824 | AI_FAMILY of socket_domain (* Impose the given socket domain *)
1825 | AI_SOCKTYPE of socket_type (* Impose the given socket type *)
1826 | AI_PROTOCOL of int (* Impose the given protocol *)
1827 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP
1828 address *)
1829 | AI_CANONNAME (* Fill the ai_canonname field of the result *)
1830 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
1831 *)
1832 Options to Unix.getaddrinfo .
1835 val getaddrinfo : string -> string -> getaddrinfo_option list ->
1840 addr_info list
1841 getaddrinfo host service opts returns a list of Unix.addr_info records
1844 describing socket parameters and addresses suitable for communicating
1845 with the given host and service. The empty list is returned if the
1846 host or service names are unknown, or the constraints expressed in opts
1847 cannot be satisfied.
1848 host is either a host name or the string representation of an IP
1851 address. host can be given as the empty string; in this case, the
1852 ``any'' address or the ``loopback'' address are used, depending whether
1853 opts contains AI_PASSIVE . service is either a service name or the
1854 string representation of a port number. service can be given as the
1855 empty string; in this case, the port field of the returned addresses is
1856 set to 0. opts is a possibly empty list of options that allows the
1857 caller to force a particular socket domain (e.g. IPv6 only or IPv4
1858 only) or a particular socket type (e.g. TCP only or UDP only).
1859 type name_info = {
1863 ni_hostname : string ; (* Name or IP address of host *)
1864 ni_service : string ;
1865 }
1866 Name of service or port number
1869 === Host and service information returned by Unix.getnameinfo. ===
1875 type getnameinfo_option =
1878 | NI_NOFQDN (* Do not qualify local host names *)
1879 | NI_NUMERICHOST (* Always return host as IP address *)
1880 | NI_NAMEREQD (* Fail if host name cannot be determined *)
1881 | NI_NUMERICSERV (* Always return service as port number *)
1882 | NI_DGRAM (* Consider the service as UDP-based instead of the
1883 default TCP *)
1884 Options to Unix.getnameinfo .
1887 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
1892 getnameinfo addr opts returns the host name and service name corre‐
1895 sponding to the socket address addr . opts is a possibly empty list of
1896 options that governs how these names are obtained. Raise Not_found if
1897 an error occurs.
1898 === Terminal interface ===
1904 === The following functions implement the POSIX standard terminal
1907 interface. They provide control over asynchronous communication ports
1908 and pseudo-terminals. Refer to the termios man page for a complete
1909 description. ===
1910 type terminal_io = {
1913 mutable c_ignbrk : bool ; (* Ignore the break condition. *)
1915 mutable c_brkint : bool ; (* Signal interrupt on break condition. *)
1917 mutable c_ignpar : bool ; (* Ignore characters with parity errors. *)
1919 mutable c_parmrk : bool ; (* Mark parity errors. *)
1921 mutable c_inpck : bool ; (* Enable parity check on input. *)
1923 mutable c_istrip : bool ; (* Strip 8th bit on input characters. *)
1925 mutable c_inlcr : bool ; (* Map NL to CR on input. *)
1927 mutable c_igncr : bool ; (* Ignore CR on input. *)
1929 mutable c_icrnl : bool ; (* Map CR to NL on input. *)
1931 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input. *)
1933 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
1935 *)
1936 mutable c_opost : bool ; (* Enable output processing. *)
1938 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
1940 tion). *)
1941 mutable c_ibaud : int ; (* Input baud rate. *)
1943 mutable c_csize : int ; (* Number of bits per character (5-8). *)
1945 mutable c_cstopb : int ; (* Number of stop bits (1-2). *)
1947 mutable c_cread : bool ; (* Reception is enabled. *)
1949 mutable c_parenb : bool ; (* Enable parity generation and detection.
1951 *)
1952 mutable c_parodd : bool ; (* Specify odd parity instead of even. *)
1954 mutable c_hupcl : bool ; (* Hang up on last close. *)
1956 mutable c_clocal : bool ; (* Ignore modem status lines. *)
1958 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP. *)
1960 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
1962 ing and editing) *)
1963 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP. *)
1965 mutable c_echo : bool ; (* Echo input characters. *)
1967 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
1969 *)
1970 mutable c_echok : bool ; (* Echo KILL (to erase the current line). *)
1972 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set. *)
1974 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C). *)
1976 mutable c_vquit : char ; (* Quit character (usually ctrl-\). *)
1978 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
1980 *)
1981 mutable c_vkill : char ; (* Kill line character (usually ctrl-U). *)
1983 mutable c_veof : char ; (* End-of-file character (usually ctrl-D). *)
1985 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
1987 *)
1988 mutable c_vmin : int ; (* Minimum number of characters to read before
1990 the read request is satisfied. *)
1991 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units). *)
1993 mutable c_vstart : char ; (* Start character (usually ctrl-Q). *)
1995 mutable c_vstop : char ; (* Stop character (usually ctrl-S). *)
1997 }
1998 val tcgetattr : file_descr -> terminal_io
2004 Return the status of the terminal referred to by the given file
2006 descriptor.
2007 type setattr_when =
2011 | TCSANOW
2012 | TCSADRAIN
2013 | TCSAFLUSH
2014 val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit
2020 Set the status of the terminal referred to by the given file descrip‐
2022 tor. The second argument indicates when the status change takes place:
2023 immediately ( TCSANOW ), when all pending output has been transmitted (
2024 TCSADRAIN ), or after flushing all input that has been received but not
2025 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2026 parameters; TCSAFLUSH , when changing the input parameters.
2027 val tcsendbreak : file_descr -> int -> unit
2032 Send a break condition on the given file descriptor. The second argu‐
2034 ment is the duration of the break, in 0.1s units; 0 means standard
2035 duration (0.25s).
2036 val tcdrain : file_descr -> unit
2041 Waits until all output written on the given file descriptor has been
2043 transmitted.
2044 type flush_queue =
2048 | TCIFLUSH
2049 | TCOFLUSH
2050 | TCIOFLUSH
2051 val tcflush : file_descr -> flush_queue -> unit
2057 Discard data written on the given file descriptor but not yet transmit‐
2059 ted, or data received but not yet read, depending on the second argu‐
2060 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2061 data written but not transmitted, and TCIOFLUSH flushes both.
2062 type flow_action =
2066 | TCOOFF
2067 | TCOON
2068 | TCIOFF
2069 | TCION
2070 val tcflow : file_descr -> flow_action -> unit
2076 Suspend or restart reception or transmission of data on the given file
2078 descriptor, depending on the second argument: TCOOFF suspends output,
2079 TCOON restarts output, TCIOFF transmits a STOP character to suspend
2080 input, and TCION transmits a START character to restart input.
2081 val setsid : unit -> int
2086 Put the calling process in a new session and detach it from its con‐
2088 trolling terminal.
2089OCamldoc 2010-01-29 Unix(3)