1Unix(3) OCamldoc 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 Note: all the functions of this module (except Unix.error_message and
19 Unix.handle_unix_error ) are liable to raise the Unix.Unix_error excep‐
20 tion whenever the underlying system call signals an error.
21 === Error report ===
29 type error =
32 | E2BIG (* Argument list too long
33 *)
34 | EACCES (* Permission denied
35 *)
36 | EAGAIN (* Resource temporarily unavailable; try again
37 *)
38 | EBADF (* Bad file descriptor
39 *)
40 | EBUSY (* Resource unavailable
41 *)
42 | ECHILD (* No child process
43 *)
44 | EDEADLK (* Resource deadlock would occur
45 *)
46 | EDOM (* Domain error for math functions, etc.
47 *)
48 | EEXIST (* File exists
49 *)
50 | EFAULT (* Bad address
51 *)
52 | EFBIG (* File too large
53 *)
54 | EINTR (* Function interrupted by signal
55 *)
56 | EINVAL (* Invalid argument
57 *)
58 | EIO (* Hardware I/O error
59 *)
60 | EISDIR (* Is a directory
61 *)
62 | EMFILE (* Too many open files by the process
63 *)
64 | EMLINK (* Too many links
65 *)
66 | ENAMETOOLONG (* Filename too long
67 *)
68 | ENFILE (* Too many open files in the system
69 *)
70 | ENODEV (* No such device
71 *)
72 | ENOENT (* No such file or directory
73 *)
74 | ENOEXEC (* Not an executable file
75 *)
76 | ENOLCK (* No locks available
77 *)
78 | ENOMEM (* Not enough memory
79 *)
80 | ENOSPC (* No space left on device
81 *)
82 | ENOSYS (* Function not supported
83 *)
84 | ENOTDIR (* Not a directory
85 *)
86 | ENOTEMPTY (* Directory not empty
87 *)
88 | ENOTTY (* Inappropriate I/O control operation
89 *)
90 | ENXIO (* No such device or address
91 *)
92 | EPERM (* Operation not permitted
93 *)
94 | EPIPE (* Broken pipe
95 *)
96 | ERANGE (* Result too large
97 *)
98 | EROFS (* Read-only file system
99 *)
100 | ESPIPE (* Invalid seek e.g. on a pipe
101 *)
102 | ESRCH (* No such process
103 *)
104 | EXDEV (* Invalid link
105 *)
106 | EWOULDBLOCK (* Operation would block
107 *)
108 | EINPROGRESS (* Operation now in progress
109 *)
110 | EALREADY (* Operation already in progress
111 *)
112 | ENOTSOCK (* Socket operation on non-socket
113 *)
114 | EDESTADDRREQ (* Destination address required
115 *)
116 | EMSGSIZE (* Message too long
117 *)
118 | EPROTOTYPE (* Protocol wrong type for socket
119 *)
120 | ENOPROTOOPT (* Protocol not available
121 *)
122 | EPROTONOSUPPORT (* Protocol not supported
123 *)
124 | ESOCKTNOSUPPORT (* Socket type not supported
125 *)
126 | EOPNOTSUPP (* Operation not supported on socket
127 *)
128 | EPFNOSUPPORT (* Protocol family not supported
129 *)
130 | EAFNOSUPPORT (* Address family not supported by protocol family
131 *)
132 | EADDRINUSE (* Address already in use
133 *)
134 | EADDRNOTAVAIL (* Can't assign requested address
135 *)
136 | ENETDOWN (* Network is down
137 *)
138 | ENETUNREACH (* Network is unreachable
139 *)
140 | ENETRESET (* Network dropped connection on reset
141 *)
142 | ECONNABORTED (* Software caused connection abort
143 *)
144 | ECONNRESET (* Connection reset by peer
145 *)
146 | ENOBUFS (* No buffer space available
147 *)
148 | EISCONN (* Socket is already connected
149 *)
150 | ENOTCONN (* Socket is not connected
151 *)
152 | ESHUTDOWN (* Can't send after socket shutdown
153 *)
154 | ETOOMANYREFS (* Too many references: can't splice
155 *)
156 | ETIMEDOUT (* Connection timed out
157 *)
158 | ECONNREFUSED (* Connection refused
159 *)
160 | EHOSTDOWN (* Host is down
161 *)
162 | EHOSTUNREACH (* No route to host
163 *)
164 | ELOOP (* Too many levels of symbolic links
165 *)
166 | EOVERFLOW (* File size or position not representable
167 *)
168 | EUNKNOWNERR of int
169 (* Unknown error
170 *)
171 The type of error codes. Errors defined in the POSIX standard and
174 additional errors from UNIX98 and BSD. All other errors are mapped to
175 EUNKNOWNERR.
176 exception Unix_error of error * string * string
180 Raised by the system calls below when an error is encountered. The
183 first component is the error code; the second component is the function
184 name; the third component is the string parameter to the function, if
185 it has one, or the empty string otherwise.
186 val error_message : error -> string
190 Return a string describing the given error code.
192 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
196 handle_unix_error f x applies f to x and returns the result. If the
199 exception Unix.Unix_error is raised, it prints a message describing the
200 error and exits with code 2.
201 === Access to the process environment ===
206 val environment : unit -> string array
209 Return the process environment, as an array of strings with the format
211 ``variable=value''.
212 val getenv : string -> string
216 Return the value associated to a variable in the process environment,
218 unless the process has special privileges.
219 Raises Not_found if the variable is unbound or the process has special
222 privileges.
223 (This function is identical to Sys.getenv .
225 val putenv : string -> string -> unit
229 Unix.putenv name value sets the value associated to a variable in the
232 process environment. name is the name of the environment variable, and
233 value its new associated value.
234 === Process handling ===
239 type process_status =
242 | WEXITED of int
243 (* The process terminated normally by exit ; the argument is the
244 return code.
245 *)
246 | WSIGNALED of int
247 (* The process was killed by a signal; the argument is the signal
248 number.
249 *)
250 | WSTOPPED of int
251 (* The process was stopped by a signal; the argument is the signal
252 number.
253 *)
254 The termination status of a process. See module Sys for the defini‐
257 tions of the standard signal numbers. Note that they are not the num‐
258 bers used by the OS.
259 type wait_flag =
262 | WNOHANG (* Do not block if no child has died yet, but immediately
263 return with a pid equal to 0.
264 *)
265 | WUNTRACED (* Report also the children that receive stop signals.
266 *)
267 Flags for Unix.waitpid .
270 val execv : string -> string array -> 'a
274 execv prog args execute the program in file prog , with the arguments
277 args , and the current process environment. These execv* functions
278 never return: on success, the current program is replaced by the new
279 one.
280 Raises Unix.Unix_error on failure.
283 val execve : string -> string array -> string array -> 'a
287 Same as Unix.execv , except that the third argument provides the envi‐
289 ronment to the program executed.
290 val execvp : string -> string array -> 'a
294 Same as Unix.execv , except that the program is searched in the path.
296 val execvpe : string -> string array -> string array -> 'a
300 Same as Unix.execve , except that the program is searched in the path.
302 val fork : unit -> int
306 Fork a new process. The returned integer is 0 for the child process,
308 the pid of the child process for the parent process.
309 On Windows: not implemented, use Unix.create_process or threads.
311 val wait : unit -> int * process_status
315 Wait until one of the children processes die, and return its pid and
317 termination status.
318 On Windows: Not implemented, use Unix.waitpid .
320 val waitpid : wait_flag list -> int -> int * process_status
324 Same as Unix.wait , but waits for the child process whose pid is given.
326 A pid of -1 means wait for any child. A pid of 0 means wait for any
327 child in the same process group as the current process. Negative pid
328 arguments represent process groups. The list of options indicates
329 whether waitpid should return immediately without waiting, and whether
330 it should report stopped children.
331 On Windows, this function can only wait for a given PID, not any child
333 process.
334 val system : string -> process_status
338 Execute the given command, wait until it terminates, and return its
340 termination status. The string is interpreted by the shell /bin/sh (or
341 the command interpreter cmd.exe on Windows) and therefore can contain
342 redirections, quotes, variables, etc. The result WEXITED 127 indicates
343 that the shell couldn't be executed.
344 val getpid : unit -> int
348 Return the pid of the process.
350 val getppid : unit -> int
354 Return the pid of the parent process. On Windows: not implemented
356 (because it is meaningless).
357 val nice : int -> int
361 Change the process priority. The integer argument is added to the
363 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
364 ties.) Return the new nice value.
365 On Windows: not implemented.
367 === Basic file input/output ===
372 type file_descr
375 The abstract type of file descriptors.
378 val stdin : file_descr
382 File descriptor for standard input.
384 val stdout : file_descr
388 File descriptor for standard output.
390 val stderr : file_descr
394 File descriptor for standard error.
396 type open_flag =
399 | O_RDONLY (* Open for reading
400 *)
401 | O_WRONLY (* Open for writing
402 *)
403 | O_RDWR (* Open for reading and writing
404 *)
405 | O_NONBLOCK (* Open in non-blocking mode
406 *)
407 | O_APPEND (* Open for append
408 *)
409 | O_CREAT (* Create if nonexistent
410 *)
411 | O_TRUNC (* Truncate to 0 length if existing
412 *)
413 | O_EXCL (* Fail if existing
414 *)
415 | O_NOCTTY (* Don't make this dev a controlling tty
416 *)
417 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
418 pletion'
419 *)
420 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
421 pletion'
422 *)
423 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
424 *)
425 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
426 still open
427 *)
428 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
429 by Unix.openfile . See Unix.set_close_on_exec for more information.
430 *)
431 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
432 default.
433 *)
434 The flags to Unix.openfile .
437 type file_perm = int
440 The type of file access rights, e.g. 0o640 is read and write for user,
443 read for group, none for others
444 val openfile : string -> open_flag list -> file_perm -> file_descr
448 Open the named file with the given flags. Third argument is the permis‐
450 sions to give to the file if it is created (see Unix.umask ). Return a
451 file descriptor on the named file.
452 val close : file_descr -> unit
456 Close a file descriptor.
458 val read : file_descr -> bytes -> int -> int -> int
462 read fd buff ofs len reads len bytes from descriptor fd , storing them
465 in byte sequence buff , starting at position ofs in buff . Return the
466 number of bytes actually read.
467 val write : file_descr -> bytes -> int -> int -> int
471 write fd buff ofs len writes len bytes to descriptor fd , taking them
474 from byte sequence buff , starting at position ofs in buff . Return the
475 number of bytes actually written. write repeats the writing operation
476 until all bytes have been written or an error occurs.
477 val single_write : file_descr -> bytes -> int -> int -> int
481 Same as write , but attempts to write only once. Thus, if an error
483 occurs, single_write guarantees that no data has been written.
484 val write_substring : file_descr -> string -> int -> int -> int
488 Same as write , but take the data from a string instead of a byte
490 sequence.
491 Since 4.02.0
494 val single_write_substring : file_descr -> string -> int -> int -> int
498 Same as single_write , but take the data from a string instead of a
500 byte sequence.
501 Since 4.02.0
504 === Interfacing with the standard input/output library ===
509 val in_channel_of_descr : file_descr -> Pervasives.in_channel
512 Create an input channel reading from the given descriptor. The channel
514 is initially in binary mode; use set_binary_mode_in ic false if text
515 mode is desired. Text mode is supported only if the descriptor refers
516 to a file or pipe, but is not supported if it refers to a socket. On
517 Windows, set_binary_mode_in always fails on channels created with this
518 function.
519 Beware that channels are buffered so more characters may have been read
521 from the file descriptor than those accessed using channel functions.
522 Channels also keep a copy of the current position in the file.
523 You need to explicitly close all channels created with this function.
525 Closing the channel also closes the underlying file descriptor (unless
526 it was already closed).
527 val out_channel_of_descr : file_descr -> Pervasives.out_channel
531 Create an output channel writing on the given descriptor. The channel
533 is initially in binary mode; use set_binary_mode_out oc false if text
534 mode is desired. Text mode is supported only if the descriptor refers
535 to a file or pipe, but is not supported if it refers to a socket. On
536 Windows, set_binary_mode_out always fails on channels created with this
537 function.
538 Beware that channels are buffered so you may have to flush them to
540 ensure that all data has been sent to the file descriptor. Channels
541 also keep a copy of the current position in the file.
542 You need to explicitly close all channels created with this function.
544 Closing the channel flushes the data and closes the underlying file
545 descriptor (unless it has already been closed, in which case the
546 buffered data is lost).
547 val descr_of_in_channel : Pervasives.in_channel -> file_descr
551 Return the descriptor corresponding to an input channel.
553 val descr_of_out_channel : Pervasives.out_channel -> file_descr
557 Return the descriptor corresponding to an output channel.
559 === Seeking and truncating ===
564 type seek_command =
567 | SEEK_SET (* indicates positions relative to the beginning of the
568 file
569 *)
570 | SEEK_CUR (* indicates positions relative to the current position
571 *)
572 | SEEK_END (* indicates positions relative to the end of the file
573 *)
574 Positioning modes for Unix.lseek .
577 val lseek : file_descr -> int -> seek_command -> int
581 Set the current position for a file descriptor, and return the result‐
583 ing offset (from the beginning of the file).
584 val truncate : string -> int -> unit
588 Truncates the named file to the given size.
590 On Windows: not implemented.
592 val ftruncate : file_descr -> int -> unit
596 Truncates the file corresponding to the given descriptor to the given
598 size.
599 On Windows: not implemented.
601 === File status ===
606 type file_kind =
609 | S_REG (* Regular file
610 *)
611 | S_DIR (* Directory
612 *)
613 | S_CHR (* Character device
614 *)
615 | S_BLK (* Block device
616 *)
617 | S_LNK (* Symbolic link
618 *)
619 | S_FIFO (* Named pipe
620 *)
621 | S_SOCK (* Socket
622 *)
623 type stats = {
628 st_dev : int ; (* Device number
629 *)
630 st_ino : int ; (* Inode number
631 *)
632 st_kind : file_kind ; (* Kind of the file
633 *)
634 st_perm : file_perm ; (* Access rights
635 *)
636 st_nlink : int ; (* Number of links
637 *)
638 st_uid : int ; (* User id of the owner
639 *)
640 st_gid : int ; (* Group ID of the file's group
641 *)
642 st_rdev : int ; (* Device minor number
643 *)
644 st_size : int ; (* Size in bytes
645 *)
646 st_atime : float ; (* Last access time
647 *)
648 st_mtime : float ; (* Last modification time
649 *)
650 st_ctime : float ; (* Last status change time
651 *)
652 }
653 The information returned by the Unix.stat calls.
656 val stat : string -> stats
660 Return the information for the named file.
662 val lstat : string -> stats
666 Same as Unix.stat , but in case the file is a symbolic link, return the
668 information for the link itself.
669 val fstat : file_descr -> stats
673 Return the information for the file associated with the given descrip‐
675 tor.
676 val isatty : file_descr -> bool
680 Return true if the given file descriptor refers to a terminal or con‐
682 sole window, false otherwise.
683 === File operations on large files ===
688 module LargeFile : sig end
691 File operations on large files. This sub-module provides 64-bit vari‐
694 ants of the functions Unix.lseek (for positioning a file descriptor),
695 Unix.truncate and Unix.ftruncate (for changing the size of a file), and
696 Unix.stat , Unix.lstat and Unix.fstat (for obtaining information on
697 files). These alternate functions represent positions and sizes by
698 64-bit integers (type int64 ) instead of regular integers (type int ),
699 thus allowing operating on files whose sizes are greater than max_int .
700 === Operations on file names ===
705 val unlink : string -> unit
708 Removes the named file.
710 If the named file is a directory, raises:
712 - EPERM on POSIX compliant system
714 - EISDIR on Linux >= 2.1.132
716 - EACCESS on Windows
718 val rename : string -> string -> unit
723 rename old new changes the name of a file from old to new .
726 val link : string -> string -> unit
730 link source dest creates a hard link named dest to the file named
733 source .
734 === File permissions and ownership ===
739 type access_permission =
742 | R_OK (* Read permission
743 *)
744 | W_OK (* Write permission
745 *)
746 | X_OK (* Execution permission
747 *)
748 | F_OK (* File exists
749 *)
750 Flags for the Unix.access call.
753 val chmod : string -> file_perm -> unit
757 Change the permissions of the named file.
759 val fchmod : file_descr -> file_perm -> unit
763 Change the permissions of an opened file. On Windows: not implemented.
765 val chown : string -> int -> int -> unit
769 Change the owner uid and owner gid of the named file. On Windows: not
771 implemented (make no sense on a DOS file system).
772 val fchown : file_descr -> int -> int -> unit
776 Change the owner uid and owner gid of an opened file. On Windows: not
778 implemented (make no sense on a DOS file system).
779 val umask : int -> int
783 Set the process's file mode creation mask, and return the previous
785 mask. On Windows: not implemented.
786 val access : string -> access_permission list -> unit
790 Check that the process has the given permissions over the named file.
792 Raises Unix_error otherwise.
795 On Windows, execute permission X_OK , cannot be tested, it just tests
797 for read permission instead.
798 === Operations on file descriptors ===
803 val dup : ?cloexec:bool -> file_descr -> file_descr
806 Return a new file descriptor referencing the same file as the given
808 descriptor. See Unix.set_close_on_exec for documentation on the
809 cloexec optional argument.
810 val dup2 : ?cloexec:bool -> file_descr -> file_descr -> unit
814 dup2 fd1 fd2 duplicates fd1 to fd2 , closing fd2 if already opened.
817 See Unix.set_close_on_exec for documentation on the cloexec optional
818 argument.
819 val set_nonblock : file_descr -> unit
823 Set the ``non-blocking'' flag on the given descriptor. When the
825 non-blocking flag is set, reading on a descriptor on which there is
826 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
827 instead of blocking; writing on a descriptor on which there is tempo‐
828 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
829 val clear_nonblock : file_descr -> unit
833 Clear the ``non-blocking'' flag on the given descriptor. See
835 Unix.set_nonblock .
836 val set_close_on_exec : file_descr -> unit
840 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
842 with the close-on-exec flag is automatically closed when the current
843 process starts another program with one of the exec , create_process
844 and open_process functions.
845 It is often a security hole to leak file descriptors opened on, say, a
847 private file to an external program: the program, then, gets access to
848 the private file and can do bad things with it. Hence, it is highly
849 recommended to set all file descriptors ``close-on-exec'', except in
850 the very few cases where a file descriptor actually needs to be trans‐
851 mitted to another program.
852 The best way to set a file descriptor ``close-on-exec'' is to create it
854 in this state. To this end, the openfile function has O_CLOEXEC and
855 O_KEEPEXEC flags to enforce ``close-on-exec'' mode or ``keep-on-exec''
856 mode, respectively. All other operations in the Unix module that cre‐
857 ate file descriptors have an optional argument ?cloexec:bool to indi‐
858 cate whether the file descriptor should be created in ``close-on-exec''
859 mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by writ‐
860 ing ~cloexec:false ). For historical reasons, the default file
861 descriptor creation mode is ``keep-on-exec'', if no cloexec optional
862 argument is given. This is not a safe default, hence it is highly rec‐
863 ommended to pass explicit cloexec arguments to operations that create
864 file descriptors.
865 The cloexec optional arguments and the O_KEEPEXEC flag were introduced
867 in OCaml 4.05. Earlier, the common practice was to create file
868 descriptors in the default, ``keep-on-exec'' mode, then call
869 set_close_on_exec on those freshly-created file descriptors. This is
870 not as safe as creating the file descriptor in ``close-on-exec'' mode
871 because, in multithreaded programs, a window of vulnerability exists
872 between the time when the file descriptor is created and the time
873 set_close_on_exec completes. If another thread spawns another program
874 during this window, the descriptor will leak, as it is still in the
875 ``keep-on-exec'' mode.
876 Regarding the atomicity guarantees given by ~cloexec:true or by the use
878 of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
879 rently-executing Caml thread cannot leak the descriptor by starting a
880 new process. On Linux, this guarantee extends to concurrently-execut‐
881 ing C threads. As of Feb 2017, other operating systems lack the neces‐
882 sary system calls and still expose a window of vulnerability during
883 which a C thread can see the newly-created file descriptor in
884 ``keep-on-exec'' mode.
885 val clear_close_on_exec : file_descr -> unit
889 Clear the ``close-on-exec'' flag on the given descriptor. See
891 Unix.set_close_on_exec .
892 === Directories ===
897 val mkdir : string -> file_perm -> unit
900 Create a directory with the given permissions (see Unix.umask ).
902 val rmdir : string -> unit
906 Remove an empty directory.
908 val chdir : string -> unit
912 Change the process working directory.
914 val getcwd : unit -> string
918 Return the name of the current working directory.
920 val chroot : string -> unit
924 Change the process root directory. On Windows: not implemented.
926 type dir_handle
929 The type of descriptors over opened directories.
932 val opendir : string -> dir_handle
936 Open a descriptor on a directory
938 val readdir : dir_handle -> string
942 Return the next entry in a directory.
944 Raises End_of_file when the end of the directory has been reached.
947 val rewinddir : dir_handle -> unit
951 Reposition the descriptor to the beginning of the directory
953 val closedir : dir_handle -> unit
957 Close a directory descriptor.
959 === Pipes and redirections ===
964 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
967 Create a pipe. The first component of the result is opened for reading,
969 that's the exit to the pipe. The second component is opened for writ‐
970 ing, that's the entrance to the pipe. See Unix.set_close_on_exec for
971 documentation on the cloexec optional argument.
972 val mkfifo : string -> file_perm -> unit
976 Create a named pipe with the given permissions (see Unix.umask ). On
978 Windows: not implemented.
979 === High-level process and redirection management ===
984 val create_process : string -> string array -> file_descr -> file_descr
987 -> file_descr -> int
988 create_process prog args new_stdin new_stdout new_stderr forks a new
991 process that executes the program in file prog , with arguments args .
992 The pid of the new process is returned immediately; the new process
993 executes concurrently with the current process. The standard input and
994 outputs of the new process are connected to the descriptors new_stdin ,
995 new_stdout and new_stderr . Passing e.g. stdout for new_stdout pre‐
996 vents the redirection and causes the new process to have the same stan‐
997 dard output as the current process. The executable file prog is
998 searched in the path. The new process has the same environment as the
999 current process.
1000 val create_process_env : string -> string array -> string array ->
1004 file_descr -> file_descr -> file_descr -> int
1005 create_process_env prog args env new_stdin new_stdout new_stderr works
1008 as Unix.create_process , except that the extra argument env specifies
1009 the environment passed to the program.
1010 val open_process_in : string -> Pervasives.in_channel
1014 High-level pipe and process management. This function runs the given
1016 command in parallel with the program. The standard output of the com‐
1017 mand is redirected to a pipe, which can be read via the returned input
1018 channel. The command is interpreted by the shell /bin/sh (or cmd.exe
1019 on Windows), cf. system .
1020 val open_process_out : string -> Pervasives.out_channel
1024 Same as Unix.open_process_in , but redirect the standard input of the
1026 command to a pipe. Data written to the returned output channel is sent
1027 to the standard input of the command. Warning: writes on output chan‐
1028 nels are buffered, hence be careful to call Pervasives.flush at the
1029 right times to ensure correct synchronization.
1030 val open_process : string -> Pervasives.in_channel * Perva‐
1034 sives.out_channel
1035 Same as Unix.open_process_out , but redirects both the standard input
1037 and standard output of the command to pipes connected to the two
1038 returned channels. The input channel is connected to the output of the
1039 command, and the output channel to the input of the command.
1040 val open_process_full : string -> string array -> Pervasives.in_channel
1044 * Pervasives.out_channel * Pervasives.in_channel
1045 Similar to Unix.open_process , but the second argument specifies the
1047 environment passed to the command. The result is a triple of channels
1048 connected respectively to the standard output, standard input, and
1049 standard error of the command.
1050 val close_process_in : Pervasives.in_channel -> process_status
1054 Close channels opened by Unix.open_process_in , wait for the associated
1056 command to terminate, and return its termination status.
1057 val close_process_out : Pervasives.out_channel -> process_status
1061 Close channels opened by Unix.open_process_out , wait for the associ‐
1063 ated command to terminate, and return its termination status.
1064 val close_process : Pervasives.in_channel * Pervasives.out_channel ->
1068 process_status
1069 Close channels opened by Unix.open_process , wait for the associated
1071 command to terminate, and return its termination status.
1072 val close_process_full : Pervasives.in_channel * Pervasives.out_channel
1076 * Pervasives.in_channel -> process_status
1077 Close channels opened by Unix.open_process_full , wait for the associ‐
1079 ated command to terminate, and return its termination status.
1080 === Symbolic links ===
1085 val symlink : ?to_dir:bool -> string -> string -> unit
1088 symlink ?to_dir source dest creates the file dest as a symbolic link to
1091 the file source . On Windows, ~to_dir indicates if the symbolic link
1092 points to a directory or a file; if omitted, symlink examines source
1093 using stat and picks appropriately, if source does not exist then false
1094 is assumed (for this reason, it is recommended that the ~to_dir parame‐
1095 ter be specified in new code). On Unix, ~to_dir is ignored.
1096 Windows symbolic links are available in Windows Vista onwards. There
1098 are some important differences between Windows symlinks and their POSIX
1099 counterparts.
1100 Windows symbolic links come in two flavours: directory and regular,
1102 which designate whether the symbolic link points to a directory or a
1103 file. The type must be correct - a directory symlink which actually
1104 points to a file cannot be selected with chdir and a file symlink which
1105 actually points to a directory cannot be read or written (note that
1106 Cygwin's emulation layer ignores this distinction).
1107 When symbolic links are created to existing targets, this distinction
1109 doesn't matter and symlink will automatically create the correct kind
1110 of symbolic link. The distinction matters when a symbolic link is cre‐
1111 ated to a non-existent target.
1112 The other caveat is that by default symbolic links are a privileged
1114 operation. Administrators will always need to be running elevated (or
1115 with UAC disabled) and by default normal user accounts need to be
1116 granted the SeCreateSymbolicLinkPrivilege via Local Security Policy
1117 (secpol.msc) or via Active Directory.
1118 Unix.has_symlink can be used to check that a process is able to create
1121 symbolic links.
1122 val has_symlink : unit -> bool
1126 Returns true if the user is able to create symbolic links. On Windows,
1128 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1129 ilege but is also running elevated, if necessary. On other platforms,
1130 this is simply indicates that the symlink system call is available.
1131 Since 4.03.0
1134 val readlink : string -> string
1138 Read the contents of a symbolic link.
1140 === Polling ===
1145 val select : file_descr list -> file_descr list -> file_descr list ->
1148 float -> file_descr list * file_descr list * file_descr list
1149 Wait until some input/output operations become possible on some chan‐
1151 nels. The three list arguments are, respectively, a set of descriptors
1152 to check for reading (first argument), for writing (second argument),
1153 or for exceptional conditions (third argument). The fourth argument is
1154 the maximal timeout, in seconds; a negative fourth argument means no
1155 timeout (unbounded wait). The result is composed of three sets of
1156 descriptors: those ready for reading (first component), ready for writ‐
1157 ing (second component), and over which an exceptional condition is
1158 pending (third component).
1159 === Locking ===
1164 type lock_command =
1167 | F_ULOCK (* Unlock a region
1168 *)
1169 | F_LOCK (* Lock a region for writing, and block if already locked
1170 *)
1171 | F_TLOCK (* Lock a region for writing, or fail if already locked
1172 *)
1173 | F_TEST (* Test a region for other process locks
1174 *)
1175 | F_RLOCK (* Lock a region for reading, and block if already locked
1176 *)
1177 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1178 *)
1179 Commands for Unix.lockf .
1182 val lockf : file_descr -> lock_command -> int -> unit
1186 lockf fd cmd size puts a lock on a region of the file opened as fd .
1189 The region starts at the current read/write position for fd (as set by
1190 Unix.lseek ), and extends size bytes forward if size is positive, size
1191 bytes backwards if size is negative, or to the end of the file if size
1192 is zero. A write lock prevents any other process from acquiring a read
1193 or write lock on the region. A read lock prevents any other process
1194 from acquiring a write lock on the region, but lets other processes
1195 acquire read locks on it.
1196 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1198 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1199 read lock on the specified region. If one or several locks put by
1200 another process prevent the current process from acquiring the lock,
1201 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1202 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1203 whatever locks the current process has on the specified region.
1204 Finally, the F_TEST command tests whether a write lock can be acquired
1205 on the specified region, without actually putting a lock. It returns
1206 immediately if successful, or fails otherwise.
1207 What happens when a process tries to lock a region of a file that is
1209 already locked by the same process depends on the OS. On POSIX-compli‐
1210 ant systems, the second lock operation succeeds and may "promote" the
1211 older lock from read lock to write lock. On Windows, the second lock
1212 operation will block or fail.
1213 === Signals Note: installation of signal handlers is performed via the
1218 functions Sys.signal and Sys.set_signal. ===
1219 val kill : int -> int -> unit
1222 kill pid sig sends signal number sig to the process with id pid . On
1225 Windows, only the Sys.sigkill signal is emulated.
1226 type sigprocmask_command =
1229 | SIG_SETMASK
1230 | SIG_BLOCK
1231 | SIG_UNBLOCK
1232 val sigprocmask : sigprocmask_command -> int list -> int list
1238 sigprocmask cmd sigs changes the set of blocked signals. If cmd is
1241 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1242 cmd is SIG_BLOCK , the signals in sigs are added to the set of blocked
1243 signals. If cmd is SIG_UNBLOCK , the signals in sigs are removed from
1244 the set of blocked signals. sigprocmask returns the set of previously
1245 blocked signals.
1246 On Windows: not implemented (no inter-process signals on Windows).
1248 val sigpending : unit -> int list
1252 Return the set of blocked signals that are currently pending.
1254 On Windows: not implemented (no inter-process signals on Windows).
1256 val sigsuspend : int list -> unit
1260 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1263 for a non-ignored, non-blocked signal to be delivered. On return, the
1264 blocked signals are reset to their initial value.
1265 On Windows: not implemented (no inter-process signals on Windows).
1267 val pause : unit -> unit
1271 Wait until a non-ignored, non-blocked signal is delivered.
1273 On Windows: not implemented (no inter-process signals on Windows).
1275 === Time functions ===
1280 type process_times = {
1283 tms_utime : float ; (* User time for the process
1284 *)
1285 tms_stime : float ; (* System time for the process
1286 *)
1287 tms_cutime : float ; (* User time for the children processes
1288 *)
1289 tms_cstime : float ; (* System time for the children processes
1290 *)
1291 }
1292 The execution times (CPU times) of a process.
1295 type tm = {
1298 tm_sec : int ; (* Seconds 0..60
1299 *)
1300 tm_min : int ; (* Minutes 0..59
1301 *)
1302 tm_hour : int ; (* Hours 0..23
1303 *)
1304 tm_mday : int ; (* Day of month 1..31
1305 *)
1306 tm_mon : int ; (* Month of year 0..11
1307 *)
1308 tm_year : int ; (* Year - 1900
1309 *)
1310 tm_wday : int ; (* Day of week (Sunday is 0)
1311 *)
1312 tm_yday : int ; (* Day of year 0..365
1313 *)
1314 tm_isdst : bool ; (* Daylight time savings in effect
1315 *)
1316 }
1317 The type representing wallclock time and calendar date.
1320 val time : unit -> float
1324 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1326 val gettimeofday : unit -> float
1330 Same as Unix.time , but with resolution better than 1 second.
1332 val gmtime : float -> tm
1336 Convert a time in seconds, as returned by Unix.time , into a date and a
1338 time. Assumes UTC (Coordinated Universal Time), also known as GMT. To
1339 perform the inverse conversion, set the TZ environment variable to
1340 "UTC", use Unix.mktime , and then restore the original value of TZ.
1341 val localtime : float -> tm
1345 Convert a time in seconds, as returned by Unix.time , into a date and a
1347 time. Assumes the local time zone. The function performing the inverse
1348 conversion is Unix.mktime .
1349 val mktime : tm -> float * tm
1353 Convert a date and time, specified by the tm argument, into a time in
1355 seconds, as returned by Unix.time . The tm_isdst , tm_wday and tm_yday
1356 fields of tm are ignored. Also return a normalized copy of the given
1357 tm record, with the tm_wday , tm_yday , and tm_isdst fields recomputed
1358 from the other fields, and the other fields normalized (so that, e.g.,
1359 40 October is changed into 9 November). The tm argument is interpreted
1360 in the local time zone.
1361 val alarm : int -> int
1365 Schedule a SIGALRM signal after the given number of seconds.
1367 On Windows: not implemented.
1369 val sleep : int -> unit
1373 Stop execution for the given number of seconds.
1375 val sleepf : float -> unit
1379 Stop execution for the given number of seconds. Like sleep , but frac‐
1381 tions of seconds are supported.
1382 Since 4.03.0
1385 val times : unit -> process_times
1389 Return the execution times of the process. On Windows, it is partially
1391 implemented, will not report timings for child processes.
1392 val utimes : string -> float -> float -> unit
1396 Set the last access time (second arg) and last modification time (third
1398 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1399 1, 1970. If both times are 0.0 , the access and last modification
1400 times are both set to the current time.
1401 type interval_timer =
1404 | ITIMER_REAL (* decrements in real time, and sends the signal
1405 SIGALRM when expired.
1406 *)
1407 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1408 SIGVTALRM when expired.
1409 *)
1410 | ITIMER_PROF (* (for profiling) decrements both when the process is
1411 running and when the system is running on behalf of the process; it
1412 sends SIGPROF when expired.
1413 *)
1414 The three kinds of interval timers.
1417 type interval_timer_status = {
1420 it_interval : float ; (* Period
1421 *)
1422 it_value : float ; (* Current value of the timer
1423 *)
1424 }
1425 The type describing the status of an interval timer
1428 val getitimer : interval_timer -> interval_timer_status
1432 Return the current status of the given interval timer.
1434 On Windows: not implemented.
1436 val setitimer : interval_timer -> interval_timer_status -> inter‐
1440 val_timer_status
1441 setitimer t s sets the interval timer t and returns its previous sta‐
1444 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1445 is the time to the next timer expiration; s.it_interval , if nonzero,
1446 specifies a value to be used in reloading it_value when the timer
1447 expires. Setting s.it_value to zero disables the timer. Setting
1448 s.it_interval to zero causes the timer to be disabled after its next
1449 expiration.
1450 On Windows: not implemented.
1452 === User id, group id ===
1457 val getuid : unit -> int
1460 Return the user id of the user executing the process. On Windows,
1462 always return 1 .
1463 val geteuid : unit -> int
1467 Return the effective user id under which the process runs. On Windows,
1469 always return 1 .
1470 val setuid : int -> unit
1474 Set the real user id and effective user id for the process. On Win‐
1476 dows: not implemented.
1477 val getgid : unit -> int
1481 Return the group id of the user executing the process. On Windows,
1483 always return 1 .
1484 val getegid : unit -> int
1488 Return the effective group id under which the process runs. On Win‐
1490 dows, always return 1 .
1491 val setgid : int -> unit
1495 Set the real group id and effective group id for the process. On Win‐
1497 dows: not implemented.
1498 val getgroups : unit -> int array
1502 Return the list of groups to which the user executing the process
1504 belongs. On Windows, always return [|1|] .
1505 val setgroups : int array -> unit
1509 setgroups groups sets the supplementary group IDs for the calling
1512 process. Appropriate privileges are required. On Windows: not imple‐
1513 mented.
1514 val initgroups : string -> int -> unit
1518 initgroups user group initializes the group access list by reading the
1521 group database /etc/group and using all groups of which user is a mem‐
1522 ber. The additional group group is also added to the list. On Windows:
1523 not implemented.
1524 type passwd_entry = {
1527 pw_name : string ;
1528 pw_passwd : string ;
1529 pw_uid : int ;
1530 pw_gid : int ;
1531 pw_gecos : string ;
1532 pw_dir : string ;
1533 pw_shell : string ;
1534 }
1535 Structure of entries in the passwd database.
1538 type group_entry = {
1541 gr_name : string ;
1542 gr_passwd : string ;
1543 gr_gid : int ;
1544 gr_mem : string array ;
1545 }
1546 Structure of entries in the groups database.
1549 val getlogin : unit -> string
1553 Return the login name of the user executing the process.
1555 val getpwnam : string -> passwd_entry
1559 Find an entry in passwd with the given name.
1561 Raises Not_found if no such entry exist.
1564 On Windows, always raise Not_found .
1566 val getgrnam : string -> group_entry
1570 Find an entry in group with the given name.
1572 Raises Not_found if no such entry exist.
1575 On Windows, always raise Not_found .
1577 val getpwuid : int -> passwd_entry
1581 Find an entry in passwd with the given user id.
1583 Raises Not_found if no such entry exist.
1586 On Windows, always raise Not_found .
1588 val getgrgid : int -> group_entry
1592 Find an entry in group with the given group id.
1594 Raises Not_found if no such entry exist.
1597 On Windows, always raise Not_found .
1599 === Internet addresses ===
1604 type inet_addr
1607 The abstract type of Internet addresses.
1610 val inet_addr_of_string : string -> inet_addr
1614 Conversion from the printable representation of an Internet address to
1616 its internal representation. The argument string consists of 4 numbers
1617 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1618 8 numbers separated by colons for IPv6 addresses.
1619 Raises Failure when given a string that does not match these formats.
1622 val string_of_inet_addr : inet_addr -> string
1626 Return the printable representation of the given Internet address. See
1628 Unix.inet_addr_of_string for a description of the printable representa‐
1629 tion.
1630 val inet_addr_any : inet_addr
1634 A special IPv4 address, for use only with bind , representing all the
1636 Internet addresses that the host machine possesses.
1637 val inet_addr_loopback : inet_addr
1641 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1643 val inet6_addr_any : inet_addr
1647 A special IPv6 address, for use only with bind , representing all the
1649 Internet addresses that the host machine possesses.
1650 val inet6_addr_loopback : inet_addr
1654 A special IPv6 address representing the host machine ( ::1 ).
1656 === Sockets ===
1661 type socket_domain =
1664 | PF_UNIX (* Unix domain
1665 *)
1666 | PF_INET (* Internet domain (IPv4)
1667 *)
1668 | PF_INET6 (* Internet domain (IPv6)
1669 *)
1670 The type of socket domains. Not all platforms support IPv6 sockets
1673 (type PF_INET6 ). Windows does not support PF_UNIX .
1674 type socket_type =
1677 | SOCK_STREAM (* Stream socket
1678 *)
1679 | SOCK_DGRAM (* Datagram socket
1680 *)
1681 | SOCK_RAW (* Raw socket
1682 *)
1683 | SOCK_SEQPACKET (* Sequenced packets socket
1684 *)
1685 The type of socket kinds, specifying the semantics of communications.
1688 SOCK_SEQPACKET is included for completeness, but is rarely supported by
1689 the OS, and needs system calls that are not available in this library.
1690 type sockaddr =
1693 | ADDR_UNIX of string
1694 | ADDR_INET of inet_addr * int
1695 (* The type of socket addresses. ADDR_UNIX name is a socket address
1696 in the Unix domain; name is a file name in the file system.
1697 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1698 is the Internet address of the machine, and port is the port number.
1699 *)
1700 val socket : ?cloexec:bool -> socket_domain -> socket_type -> int ->
1706 file_descr
1707 Create a new socket in the given domain, and with the given kind. The
1709 third argument is the protocol type; 0 selects the default protocol for
1710 that kind of sockets. See Unix.set_close_on_exec for documentation on
1711 the cloexec optional argument.
1712 val domain_of_sockaddr : sockaddr -> socket_domain
1716 Return the socket domain adequate for the given socket address.
1718 val socketpair : ?cloexec:bool -> socket_domain -> socket_type -> int
1722 -> file_descr * file_descr
1723 Create a pair of unnamed sockets, connected together. See
1725 Unix.set_close_on_exec for documentation on the cloexec optional argu‐
1726 ment.
1727 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1731 Accept connections on the given socket. The returned descriptor is a
1733 socket connected to the client; the returned address is the address of
1734 the connecting client. See Unix.set_close_on_exec for documentation on
1735 the cloexec optional argument.
1736 val bind : file_descr -> sockaddr -> unit
1740 Bind a socket to an address.
1742 val connect : file_descr -> sockaddr -> unit
1746 Connect a socket to an address.
1748 val listen : file_descr -> int -> unit
1752 Set up a socket for receiving connection requests. The integer argument
1754 is the maximal number of pending requests.
1755 type shutdown_command =
1758 | SHUTDOWN_RECEIVE (* Close for receiving
1759 *)
1760 | SHUTDOWN_SEND (* Close for sending
1761 *)
1762 | SHUTDOWN_ALL (* Close both
1763 *)
1764 The type of commands for shutdown .
1767 val shutdown : file_descr -> shutdown_command -> unit
1771 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
1773 reads on the other end of the connection to return an end-of-file con‐
1774 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
1775 tion to return a closed pipe condition ( SIGPIPE signal).
1776 val getsockname : file_descr -> sockaddr
1780 Return the address of the given socket.
1782 val getpeername : file_descr -> sockaddr
1786 Return the address of the host connected to the given socket.
1788 type msg_flag =
1791 | MSG_OOB
1792 | MSG_DONTROUTE
1793 | MSG_PEEK (* The flags for Unix.recv , Unix.recvfrom , Unix.send and
1794 Unix.sendto .
1795 *)
1796 val recv : file_descr -> bytes -> int -> int -> msg_flag list -> int
1802 Receive data from a connected socket.
1804 val recvfrom : file_descr -> bytes -> int -> int -> msg_flag list ->
1808 int * sockaddr
1809 Receive data from an unconnected socket.
1811 val send : file_descr -> bytes -> int -> int -> msg_flag list -> int
1815 Send data over a connected socket.
1817 val send_substring : file_descr -> string -> int -> int -> msg_flag
1821 list -> int
1822 Same as send , but take the data from a string instead of a byte
1824 sequence.
1825 Since 4.02.0
1828 val sendto : file_descr -> bytes -> int -> int -> msg_flag list ->
1832 sockaddr -> int
1833 Send data over an unconnected socket.
1835 val sendto_substring : file_descr -> string -> int -> int -> msg_flag
1839 list -> sockaddr -> int
1840 Same as sendto , but take the data from a string instead of a byte
1842 sequence.
1843 Since 4.02.0
1846 === Socket options ===
1851 type socket_bool_option =
1854 | SO_DEBUG (* Record debugging information
1855 *)
1856 | SO_BROADCAST (* Permit sending of broadcast messages
1857 *)
1858 | SO_REUSEADDR (* Allow reuse of local addresses for bind
1859 *)
1860 | SO_KEEPALIVE (* Keep connection active
1861 *)
1862 | SO_DONTROUTE (* Bypass the standard routing algorithms
1863 *)
1864 | SO_OOBINLINE (* Leave out-of-band data in line
1865 *)
1866 | SO_ACCEPTCONN (* Report whether socket listening is enabled
1867 *)
1868 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
1869 *)
1870 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
1871 *)
1872 The socket options that can be consulted with Unix.getsockopt and modi‐
1875 fied with Unix.setsockopt . These options have a boolean ( true /
1876 false ) value.
1877 type socket_int_option =
1880 | SO_SNDBUF (* Size of send buffer
1881 *)
1882 | SO_RCVBUF (* Size of received buffer
1883 *)
1884 | SO_ERROR (* Deprecated. Use Unix.getsockopt_error instead.
1885 *)
1886 | SO_TYPE (* Report the socket type
1887 *)
1888 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
1889 tions
1890 *)
1891 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
1892 tions
1893 *)
1894 The socket options that can be consulted with Unix.getsockopt_int and
1897 modified with Unix.setsockopt_int . These options have an integer
1898 value.
1899 type socket_optint_option =
1902 | SO_LINGER (* Whether to linger on closed connections that have data
1903 present, and for how long (in seconds)
1904 *)
1905 The socket options that can be consulted with Unix.getsockopt_optint
1908 and modified with Unix.setsockopt_optint . These options have a value
1909 of type int option , with None meaning ``disabled''.
1910 type socket_float_option =
1913 | SO_RCVTIMEO (* Timeout for input operations
1914 *)
1915 | SO_SNDTIMEO (* Timeout for output operations
1916 *)
1917 The socket options that can be consulted with Unix.getsockopt_float and
1920 modified with Unix.setsockopt_float . These options have a float‐
1921 ing-point value representing a time in seconds. The value 0 means
1922 infinite timeout.
1923 val getsockopt : file_descr -> socket_bool_option -> bool
1927 Return the current status of a boolean-valued option in the given
1929 socket.
1930 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
1934 Set or clear a boolean-valued option in the given socket.
1936 val getsockopt_int : file_descr -> socket_int_option -> int
1940 Same as Unix.getsockopt for an integer-valued socket option.
1942 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
1946 Same as Unix.setsockopt for an integer-valued socket option.
1948 val getsockopt_optint : file_descr -> socket_optint_option -> int
1952 option
1953 Same as Unix.getsockopt for a socket option whose value is an int
1955 option .
1956 val setsockopt_optint : file_descr -> socket_optint_option -> int
1960 option -> unit
1961 Same as Unix.setsockopt for a socket option whose value is an int
1963 option .
1964 val getsockopt_float : file_descr -> socket_float_option -> float
1968 Same as Unix.getsockopt for a socket option whose value is a float‐
1970 ing-point number.
1971 val setsockopt_float : file_descr -> socket_float_option -> float ->
1975 unit
1976 Same as Unix.setsockopt for a socket option whose value is a float‐
1978 ing-point number.
1979 val getsockopt_error : file_descr -> error option
1983 Return the error condition associated with the given socket, and clear
1985 it.
1986 === High-level network connection functions ===
1991 val open_connection : sockaddr -> Pervasives.in_channel * Perva‐
1994 sives.out_channel
1995 Connect to a server at the given address. Return a pair of buffered
1997 channels connected to the server. Remember to call Pervasives.flush on
1998 the output channel at the right times to ensure correct synchroniza‐
1999 tion.
2000 val shutdown_connection : Pervasives.in_channel -> unit
2004 ``Shut down'' a connection established with Unix.open_connection ; that
2006 is, transmit an end-of-file condition to the server reading on the
2007 other side of the connection. This does not fully close the file
2008 descriptor associated with the channel, which you must remember to free
2009 via Pervasives.close_in .
2010 val establish_server : (Pervasives.in_channel -> Pervasives.out_channel
2014 -> unit) -> sockaddr -> unit
2015 Establish a server on the given address. The function given as first
2017 argument is called for each connection with two buffered channels con‐
2018 nected to the client. A new process is created for each connection. The
2019 function Unix.establish_server never returns normally.
2020 On Windows, it is not implemented. Use threads.
2022 === Host and protocol databases ===
2027 type host_entry = {
2030 h_name : string ;
2031 h_aliases : string array ;
2032 h_addrtype : socket_domain ;
2033 h_addr_list : inet_addr array ;
2034 }
2035 Structure of entries in the hosts database.
2038 type protocol_entry = {
2041 p_name : string ;
2042 p_aliases : string array ;
2043 p_proto : int ;
2044 }
2045 Structure of entries in the protocols database.
2048 type service_entry = {
2051 s_name : string ;
2052 s_aliases : string array ;
2053 s_port : int ;
2054 s_proto : string ;
2055 }
2056 Structure of entries in the services database.
2059 val gethostname : unit -> string
2063 Return the name of the local host.
2065 val gethostbyname : string -> host_entry
2069 Find an entry in hosts with the given name.
2071 Raises Not_found if no such entry exist.
2074 val gethostbyaddr : inet_addr -> host_entry
2078 Find an entry in hosts with the given address.
2080 Raises Not_found if no such entry exist.
2083 val getprotobyname : string -> protocol_entry
2087 Find an entry in protocols with the given name.
2089 Raises Not_found if no such entry exist.
2092 val getprotobynumber : int -> protocol_entry
2096 Find an entry in protocols with the given protocol number.
2098 Raises Not_found if no such entry exist.
2101 val getservbyname : string -> string -> service_entry
2105 Find an entry in services with the given name.
2107 Raises Not_found if no such entry exist.
2110 val getservbyport : int -> string -> service_entry
2114 Find an entry in services with the given service number.
2116 Raises Not_found if no such entry exist.
2119 type addr_info = {
2122 ai_family : socket_domain ; (* Socket domain
2123 *)
2124 ai_socktype : socket_type ; (* Socket type
2125 *)
2126 ai_protocol : int ; (* Socket protocol number
2127 *)
2128 ai_addr : sockaddr ; (* Address
2129 *)
2130 ai_canonname : string ; (* Canonical host name
2131 *)
2132 }
2133 Address information returned by Unix.getaddrinfo .
2136 type getaddrinfo_option =
2139 | AI_FAMILY of socket_domain
2140 (* Impose the given socket domain
2141 *)
2142 | AI_SOCKTYPE of socket_type
2143 (* Impose the given socket type
2144 *)
2145 | AI_PROTOCOL of int
2146 (* Impose the given protocol
2147 *)
2148 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP
2149 address
2150 *)
2151 | AI_CANONNAME (* Fill the ai_canonname field of the result
2152 *)
2153 | AI_PASSIVE (* Set address to ``any'' address for use with Unix.bind
2154 *)
2156 Options to Unix.getaddrinfo .
2159 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2163 addr_info list
2164 getaddrinfo host service opts returns a list of Unix.addr_info records
2167 describing socket parameters and addresses suitable for communicating
2168 with the given host and service. The empty list is returned if the
2169 host or service names are unknown, or the constraints expressed in opts
2170 cannot be satisfied.
2171 host is either a host name or the string representation of an IP
2174 address. host can be given as the empty string; in this case, the
2175 ``any'' address or the ``loopback'' address are used, depending whether
2176 opts contains AI_PASSIVE . service is either a service name or the
2177 string representation of a port number. service can be given as the
2178 empty string; in this case, the port field of the returned addresses is
2179 set to 0. opts is a possibly empty list of options that allows the
2180 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2181 only) or a particular socket type (e.g. TCP only or UDP only).
2182 type name_info = {
2185 ni_hostname : string ; (* Name or IP address of host
2186 *)
2187 ni_service : string ; (* Name of service or port number
2188 *)
2189 }
2190 Host and service information returned by Unix.getnameinfo .
2193 type getnameinfo_option =
2196 | NI_NOFQDN (* Do not qualify local host names
2197 *)
2198 | NI_NUMERICHOST (* Always return host as IP address
2199 *)
2200 | NI_NAMEREQD (* Fail if host name cannot be determined
2201 *)
2202 | NI_NUMERICSERV (* Always return service as port number
2203 *)
2204 | NI_DGRAM (* Consider the service as UDP-based instead of the
2205 default TCP
2206 *)
2207 Options to Unix.getnameinfo .
2210 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2214 getnameinfo addr opts returns the host name and service name corre‐
2217 sponding to the socket address addr . opts is a possibly empty list of
2218 options that governs how these names are obtained.
2219 Raises Not_found if an error occurs.
2222 === Terminal interface ===
2227 === The following functions implement the POSIX standard terminal
2230 interface. They provide control over asynchronous communication ports
2231 and pseudo-terminals. Refer to the termios man page for a complete
2232 description. ===
2233 type terminal_io = {
2236 mutable c_ignbrk : bool ; (* Ignore the break condition.
2238 *)
2239 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2241 *)
2242 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2244 *)
2245 mutable c_parmrk : bool ; (* Mark parity errors.
2247 *)
2248 mutable c_inpck : bool ; (* Enable parity check on input.
2250 *)
2251 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2253 *)
2254 mutable c_inlcr : bool ; (* Map NL to CR on input.
2256 *)
2257 mutable c_igncr : bool ; (* Ignore CR on input.
2259 *)
2260 mutable c_icrnl : bool ; (* Map CR to NL on input.
2262 *)
2263 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2265 *)
2266 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2268 *)
2269 mutable c_opost : bool ; (* Enable output processing.
2271 *)
2272 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2274 tion).
2275 *)
2276 mutable c_ibaud : int ; (* Input baud rate.
2278 *)
2279 mutable c_csize : int ; (* Number of bits per character (5-8).
2281 *)
2282 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2284 *)
2285 mutable c_cread : bool ; (* Reception is enabled.
2287 *)
2288 mutable c_parenb : bool ; (* Enable parity generation and detection.
2290 *)
2291 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2293 *)
2294 mutable c_hupcl : bool ; (* Hang up on last close.
2296 *)
2297 mutable c_clocal : bool ; (* Ignore modem status lines.
2299 *)
2300 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2302 *)
2303 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2305 ing and editing)
2306 *)
2307 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2309 *)
2310 mutable c_echo : bool ; (* Echo input characters.
2312 *)
2313 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2315 *)
2316 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2318 *)
2319 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2321 *)
2322 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2324 *)
2325 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2327 *)
2328 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2330 *)
2331 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2333 *)
2334 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2336 *)
2337 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2339 *)
2340 mutable c_vmin : int ; (* Minimum number of characters to read before
2342 the read request is satisfied.
2343 *)
2344 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2346 *)
2347 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2349 *)
2350 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2352 *)
2353 }
2354 val tcgetattr : file_descr -> terminal_io
2360 Return the status of the terminal referred to by the given file
2362 descriptor. On Windows, not implemented.
2363 type setattr_when =
2366 | TCSANOW
2367 | TCSADRAIN
2368 | TCSAFLUSH
2369 val tcsetattr : file_descr -> setattr_when -> terminal_io -> unit
2375 Set the status of the terminal referred to by the given file descrip‐
2377 tor. The second argument indicates when the status change takes place:
2378 immediately ( TCSANOW ), when all pending output has been transmitted (
2379 TCSADRAIN ), or after flushing all input that has been received but not
2380 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2381 parameters; TCSAFLUSH , when changing the input parameters.
2382 On Windows, not implemented.
2384 val tcsendbreak : file_descr -> int -> unit
2388 Send a break condition on the given file descriptor. The second argu‐
2390 ment is the duration of the break, in 0.1s units; 0 means standard
2391 duration (0.25s).
2392 On Windows, not implemented.
2394 val tcdrain : file_descr -> unit
2398 Waits until all output written on the given file descriptor has been
2400 transmitted.
2401 On Windows, not implemented.
2403 type flush_queue =
2406 | TCIFLUSH
2407 | TCOFLUSH
2408 | TCIOFLUSH
2409 val tcflush : file_descr -> flush_queue -> unit
2415 Discard data written on the given file descriptor but not yet transmit‐
2417 ted, or data received but not yet read, depending on the second argu‐
2418 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2419 data written but not transmitted, and TCIOFLUSH flushes both.
2420 On Windows, not implemented.
2422 type flow_action =
2425 | TCOOFF
2426 | TCOON
2427 | TCIOFF
2428 | TCION
2429 val tcflow : file_descr -> flow_action -> unit
2435 Suspend or restart reception or transmission of data on the given file
2437 descriptor, depending on the second argument: TCOOFF suspends output,
2438 TCOON restarts output, TCIOFF transmits a STOP character to suspend
2439 input, and TCION transmits a START character to restart input.
2440 On Windows, not implemented.
2442 val setsid : unit -> int
2446 Put the calling process in a new session and detach it from its con‐
2448 trolling terminal.
2449 On Windows, not implemented.
24512018-04-14 source: Unix(3)