QingdaoU/oj-docs
1
0
Fork 0
mirror of https://github.com/QingdaoU/oj-docs.git synced 2025-01-16 16:32:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

git config core.ignorecase false

Browse Source
This commit is contained in:
virusdefender 2016-10-05 23:50:36 +08:00
parent 03b9a058a3
commit 0afe3a2f72
4 changed files with 725 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

357
docs/Judger/English/index.html Normal file
View File

@ -0,0 +1,357 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>API - Online Judge Docs</title>
<link href="../../css/bootstrap-custom.min.css" rel="stylesheet">
<link href="../../css/font-awesome-4.0.3.css" rel="stylesheet">
<link rel="stylesheet" href="../../css/highlight.css">
<link href="../../css/base.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
</head>
<body>
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<!-- Main title -->
<a class="navbar-brand" href="../..">Online Judge Docs</a>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li >
<a href="../..">Home</a>
</li>
<li class="dropdown active">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Judger <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../">index</a>
</li>
<li class="dropdown-submenu">
<a tabindex="-1" href="">English</a>
<ul class="dropdown-menu">
<li class="active">
<a href="./">API</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">JudgeServer <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../../JudgeServer/">index</a>
</li>
<li class="dropdown-submenu">
<a tabindex="-1" href="">English</a>
<ul class="dropdown-menu">
<li >
<a href="../../JudgeServer/English/">API</a>
</li>
<li >
<a href="../../JudgeServer/English/deploy/">Deploy</a>
</li>
</ul>
</li>
<li class="dropdown-submenu">
<a tabindex="-1" href="">中文</a>
<ul class="dropdown-menu">
<li >
<a href="../../JudgeServer/Chinese/">API</a>
</li>
<li >
<a href="../../JudgeServer/Chinese/deploy/">部署</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<!-- Search, Navigation and Repo links -->
<ul class="nav navbar-nav navbar-right">
<li>
<a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li >
<a rel="next" href="../">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li >
<a rel="prev" href="../../JudgeServer/">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
<ul class="nav bs-sidenav">
<li class="main active"><a href="#judger-for-onlinejudge">Judger for OnlineJudge</a></li>
<li><a href="#build">build</a></li>
<li><a href="#c-api">C API</a></li>
<li><a href="#struct-config-members">struct config members</a></li>
<li><a href="#struct-result-members">struct result members</a></li>
<li><a href="#python-binding-python-27-only">Python binding (Python 2.7 only)</a></li>
<li><a href="#run-tests">Run tests</a></li>
<li><a href="#note">Note</a></li>
<li><a href="#license">License</a></li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<h1 id="judger-for-onlinejudge">Judger for OnlineJudge</h1>
<h2 id="build">build</h2>
<pre><code>sudo apt-get install libseccomp-dev
mkdir build &amp;&amp; cd build &amp;&amp; cmake .. &amp;&amp; make &amp;&amp; sudo make install
</code></pre>
<h2 id="c-api">C API</h2>
<p><code>#include &lt;runner.h&gt;</code> then call <code>run</code> function with <code>struct config</code> and <code>struct result</code> pointer.</p>
<h2 id="struct-config-members"><code>struct config</code> members</h2>
<ul>
<li><code>max_cpu_time</code> (ms): max cpu time this process can cost, -1 for unlimited</li>
<li><code>max_real_time</code> (ms): max time this process can run, -1 for unlimited</li>
<li><code>max_memory</code> (byte): max size of the process's virtual memory (address space), -1 for unlimited</li>
<li><code>max_process_number</code>: max number of child process this process can create (to avoid fork bomb), -1 for unlimited</li>
<li><code>max_output_size</code> (byte): max size of data this process can output to stdout, stderr and file, -1 for unlimited</li>
<li><code>exe_path</code>: path of file to run</li>
<li><code>input_file</code>: redirect content of this file to process's stdin</li>
<li><code>output_file</code>: redirect process's stdout to this file</li>
<li><code>error_file</code>: redirect process's stderr to this file</li>
<li><code>args</code> (string array terminated by NULL): arguments to run this process</li>
<li><code>env</code> (string array terminated by NULL): environment variables this process can get</li>
<li><code>log_path</code>: judger log path</li>
<li><code>seccomp_rule_so_path</code>(string or NULL): seccomp rules used to limit process system calls</li>
<li><code>uid</code>: user to run this process</li>
<li><code>gid</code>: user group this process belongs to</li>
</ul>
<h2 id="struct-result-members"><code>struct result</code> members</h2>
<ul>
<li><code>cpu_time</code>: cpu time the process has used</li>
<li><code>real_time</code>: actual running time of the process</li>
<li><code>signal</code>: signal number</li>
<li><code>exit_code</code>: process's exit code</li>
<li><code>result</code>: judger result, details in <code>runner.h</code></li>
<li><code>error</code>: args validation error or judger internal error, error code in <code>runner.h</code></li>
</ul>
<h3 id="result-return-value"><code>result</code> return value</h3>
<ul>
<li>WRONG_ANSWER (judger module will never return this value, it's used for awswer checker)</li>
<li>SUCCESS = 0 (this only means the process exited normally)</li>
<li>CPU_TIME_LIMIT_EXCEEDED = 1 </li>
<li>REAL_TIME_LIMIT_EXCEEDED = 2</li>
<li>MEMORY_LIMIT_EXCEEDED = 3</li>
<li>RUNTIME_ERROR = 4</li>
<li>SYSTEM_ERROR = 5</li>
</ul>
<h3 id="error-return-value"><code>error</code> return value</h3>
<ul>
<li>SUCCESS = 0</li>
<li>INVALID_CONFIG = -1</li>
<li>CLONE_FAILED = -2</li>
<li>PTHREAD_FAILED = -3</li>
<li>WAIT_FAILED = -4</li>
<li>ROOT_REQUIRED = -5</li>
<li>LOAD_SECCOMP_FAILED = -6</li>
<li>SETRLIMIT_FAILED = -7</li>
<li>DUP2_FAILED = -8</li>
<li>SETUID_FAILED = -9</li>
<li>EXECVE_FAILED = -10</li>
<li>SPJ_ERROR = -11 (judger module will never return this value, it's used for awswer checker)</li>
</ul>
<h2 id="python-binding-python-27-only">Python binding (Python 2.7 only)</h2>
<pre><code>sudo python setup.py install
</code></pre>
<h3 id="python-demo">Python demo</h3>
<p>Args with string must be Python <code>str</code> type</p>
<pre><code>&gt;&gt;&gt; import _judger
&gt;&gt;&gt; _judger.VERSION
[2, 0, 1]
&gt;&gt;&gt; _judger.run(max_cpu_time=1000,
... max_real_time=2000,
... max_memory=1000000000,
... max_process_number=200,
... max_output_size=10000,
... # five args above can be _judger.UNLIMITED
... exe_path=&quot;/bin/echo&quot;,
... input_path=&quot;/dev/null&quot;,
... output_path=&quot;echo.out&quot;,
... error_path=&quot;echo.out&quot;,
... # can be empty list
... args=[&quot;HelloWorld&quot;],
... # can be empty list
... env=[&quot;foo=bar&quot;],
... log_path=&quot;judger.log&quot;,
... # can be None
... seccomp_rule_so_path=&quot;/usr/lib/judger/librule_c_cpp.so&quot;,
... uid=0,
... gid=0)
{'cpu_time': 0, 'signal': 0, 'memory': 4554752, 'exit_code': 0, 'result': 0, 'error': 0, 'real_time': 2}
</code></pre>
<p>There are six constants in the module you can use</p>
<ul>
<li>RESULT_SUCCESS</li>
<li>RESULT_CPU_TIME_LIMIT_EXCEEDED</li>
<li>RESULT_REAL_TIME_LIMIT_EXCEEDED</li>
<li>RESULT_MEMORY_LIMIT_EXCEEDED</li>
<li>RESULT_RUNTIME_ERROR</li>
<li>RESULT_SYSTEM_ERROR</li>
</ul>
<h2 id="run-tests">Run tests</h2>
<pre><code>cd tests &amp;&amp; sudo python test.py
</code></pre>
<h2 id="note">Note</h2>
<ul>
<li>Linux x64 and kernel version &gt; 3.17 required</li>
<li>Judger security relies on Docker with default security config <a href="./todo">More</a></li>
<li>Tested under Ubuntu 14.04 docker container. System calls may vary due to different system and kernel versions</li>
<li>Root user required to change uid / gid</li>
<li>Why use seccomp instead of ptrace? Ptrace can decrease process's performance significantly, for each system call, twice
context switch between child process and parent process is needed.</li>
<li>How to custom seccomp rule? <a href="https://github.com/QingdaoU/Judger/blob/newnew/src/rules/c_cpp/rule.c">Example here</a>, then reinstall jduger, your code will be compiled and installed under
<code>/usr/lib/judger</code></li>
</ul>
<h2 id="license">License</h2>
<p>The Star And Thank Author License (SATA)</p></div>
</div>
<footer class="col-md-12">
<hr>
<center>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</center>
</footer>
<script src="../../js/jquery-1.10.2.min.js"></script>
<script src="../../js/bootstrap-3.0.3.min.js"></script>
<script src="../../js/highlight.pack.js"></script>
<script>var base_url = '../..';</script>
<script data-main="../../mkdocs/js/search.js" src="../../mkdocs/js/require.js"></script>
<script src="../../js/base.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="Search Modal" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
<h4 class="modal-title" id="exampleModalLabel">Search</h4>
</div>
<div class="modal-body">
<p>
From here you can search these documents. Enter
your search terms below.
</p>
<form role="form">
<div class="form-group">
<input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query">
</div>
</form>
<div id="mkdocs-search-results"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>

231
docs/Judger/index.html Normal file
View File

@ -0,0 +1,231 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="shortcut icon" href="../img/favicon.ico">
<title>index - Online Judge Docs</title>
<link href="../css/bootstrap-custom.min.css" rel="stylesheet">
<link href="../css/font-awesome-4.0.3.css" rel="stylesheet">
<link rel="stylesheet" href="../css/highlight.css">
<link href="../css/base.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
<![endif]-->
</head>
<body>
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<!-- Collapsed navigation -->
<div class="navbar-header">
<!-- Expander button -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<!-- Main title -->
<a class="navbar-brand" href="..">Online Judge Docs</a>
</div>
<!-- Expanded navigation -->
<div class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li >
<a href="..">Home</a>
</li>
<li class="dropdown active">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Judger <b class="caret"></b></a>
<ul class="dropdown-menu">
<li class="active">
<a href="./">index</a>
</li>
<li class="dropdown-submenu">
<a tabindex="-1" href="">English</a>
<ul class="dropdown-menu">
<li >
<a href="English/">API</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">JudgeServer <b class="caret"></b></a>
<ul class="dropdown-menu">
<li >
<a href="../JudgeServer/">index</a>
</li>
<li class="dropdown-submenu">
<a tabindex="-1" href="">English</a>
<ul class="dropdown-menu">
<li >
<a href="../JudgeServer/English/">API</a>
</li>
<li >
<a href="../JudgeServer/English/deploy/">Deploy</a>
</li>
</ul>
</li>
<li class="dropdown-submenu">
<a tabindex="-1" href="">中文</a>
<ul class="dropdown-menu">
<li >
<a href="../JudgeServer/Chinese/">API</a>
</li>
<li >
<a href="../JudgeServer/Chinese/deploy/">部署</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<!-- Search, Navigation and Repo links -->
<ul class="nav navbar-nav navbar-right">
<li>
<a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li >
<a rel="next" href="..">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li >
<a rel="prev" href="English/">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
<ul class="nav bs-sidenav">
<li class="main active"><a href="#table-of-contents">Table of contents</a></li>
</ul>
</div></div>
<div class="col-md-9" role="main">
<h1 id="table-of-contents">Table of contents</h1>
<ul>
<li>Judger <ul>
<li>English <ul>
<li><a href="../Judger/English/">API</a></li>
</ul>
</li>
</ul>
</li>
</ul></div>
</div>
<footer class="col-md-12">
<hr>
<center>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</center>
</footer>
<script src="../js/jquery-1.10.2.min.js"></script>
<script src="../js/bootstrap-3.0.3.min.js"></script>
<script src="../js/highlight.pack.js"></script>
<script>var base_url = '..';</script>
<script data-main="../mkdocs/js/search.js" src="../mkdocs/js/require.js"></script>
<script src="../js/base.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="Search Modal" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">&times;</span><span class="sr-only">Close</span></button>
<h4 class="modal-title" id="exampleModalLabel">Search</h4>
</div>
<div class="modal-body">
<p>
From here you can search these documents. Enter
your search terms below.
</p>
<form role="form">
<div class="form-group">
<input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query">
</div>
</form>
<div id="mkdocs-search-results"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>

133
src/Judger/English/index.md Normal file
View File

@ -0,0 +1,133 @@
# Judger for OnlineJudge
## build
```
sudo apt-get install libseccomp-dev
mkdir build && cd build && cmake .. && make && sudo make install
```
## C API
`#include <runner.h>` then call `run` function with `struct config` and `struct result` pointer.
## `struct config` members
- `max_cpu_time` (ms): max cpu time this process can cost, -1 for unlimited
- `max_real_time` (ms): max time this process can run, -1 for unlimited
- `max_memory` (byte): max size of the process's virtual memory (address space), -1 for unlimited
- `max_process_number`: max number of child process this process can create (to avoid fork bomb), -1 for unlimited
- `max_output_size` (byte): max size of data this process can output to stdout, stderr and file, -1 for unlimited
- `exe_path`: path of file to run
- `input_file`: redirect content of this file to process's stdin
- `output_file`: redirect process's stdout to this file
- `error_file`: redirect process's stderr to this file
- `args` (string array terminated by NULL): arguments to run this process
- `env` (string array terminated by NULL): environment variables this process can get
- `log_path`: judger log path
- `seccomp_rule_so_path`(string or NULL): seccomp rules used to limit process system calls
- `uid`: user to run this process
- `gid`: user group this process belongs to
## `struct result` members
- `cpu_time`: cpu time the process has used
- `real_time`: actual running time of the process
- `signal`: signal number
- `exit_code`: process's exit code
- `result`: judger result, details in `runner.h`
- `error`: args validation error or judger internal error, error code in `runner.h`
### `result` return value
- WRONG_ANSWER (judger module will never return this value, it's used for awswer checker)
- SUCCESS = 0 (this only means the process exited normally)
- CPU_TIME_LIMIT_EXCEEDED = 1
- REAL_TIME_LIMIT_EXCEEDED = 2
- MEMORY_LIMIT_EXCEEDED = 3
- RUNTIME_ERROR = 4
- SYSTEM_ERROR = 5
### `error` return value
- SUCCESS = 0
- INVALID_CONFIG = -1
- CLONE_FAILED = -2
- PTHREAD_FAILED = -3
- WAIT_FAILED = -4
- ROOT_REQUIRED = -5
- LOAD_SECCOMP_FAILED = -6
- SETRLIMIT_FAILED = -7
- DUP2_FAILED = -8
- SETUID_FAILED = -9
- EXECVE_FAILED = -10
- SPJ_ERROR = -11 (judger module will never return this value, it's used for awswer checker)
## Python binding (Python 2.7 only)
```
sudo python setup.py install
```
### Python demo
Args with string must be Python `str` type
```
>>> import _judger
>>> _judger.VERSION
[2, 0, 1]
>>> _judger.run(max_cpu_time=1000,
... max_real_time=2000,
... max_memory=1000000000,
... max_process_number=200,
... max_output_size=10000,
... # five args above can be _judger.UNLIMITED
... exe_path="/bin/echo",
... input_path="/dev/null",
... output_path="echo.out",
... error_path="echo.out",
... # can be empty list
... args=["HelloWorld"],
... # can be empty list
... env=["foo=bar"],
... log_path="judger.log",
... # can be None
... seccomp_rule_so_path="/usr/lib/judger/librule_c_cpp.so",
... uid=0,
... gid=0)
{'cpu_time': 0, 'signal': 0, 'memory': 4554752, 'exit_code': 0, 'result': 0, 'error': 0, 'real_time': 2}
```
There are six constants in the module you can use
- RESULT_SUCCESS
- RESULT_CPU_TIME_LIMIT_EXCEEDED
- RESULT_REAL_TIME_LIMIT_EXCEEDED
- RESULT_MEMORY_LIMIT_EXCEEDED
- RESULT_RUNTIME_ERROR
- RESULT_SYSTEM_ERROR
## Run tests
```
cd tests && sudo python test.py
```
## Note
- Linux x64 and kernel version > 3.17 required
- Judger security relies on Docker with default security config [More](todo)
- Tested under Ubuntu 14.04 docker container. System calls may vary due to different system and kernel versions
- Root user required to change uid / gid
- Why use seccomp instead of ptrace? Ptrace can decrease process's performance significantly, for each system call, twice
context switch between child process and parent process is needed.
- How to custom seccomp rule? [Example here](https://github.com/QingdaoU/Judger/blob/newnew/src/rules/c_cpp/rule.c), then reinstall jduger, your code will be compiled and installed under
`/usr/lib/judger`
## License
The Star And Thank Author License (SATA)

4
src/Judger/index.md Normal file
View File

@ -0,0 +1,4 @@
# Table of contents
- Judger
- English
- [API](/Judger/English/)